GrowthBook

GrowthBook MCP Thin

Máy chủ MCP mỏng (thin) cho GrowthBook với bốn công cụ:

Công cụ	Mục đích
growthbook_list_skills	Liệt kê các kỹ năng agent GrowthBook được đóng gói (tên + mô tả)
growthbook_read_skill	Trả về toàn bộ nội dung markdown kỹ năng (quy trình + rào cản)
growthbook_api_read	Chuyển tiếp GET có xác thực tới GrowthBook API
growthbook_api_write	Chuyển tiếp POST/PUT/PATCH/DELETE có xác thực

Năng lực nằm trong repo skills và được đóng gói tại thời điểm build. Khả năng được tách thành các công cụ API đọc so với ghi (không có formatter theo từng endpoint) để client có thể tôn trọng readOnlyHint / destructiveHint một cách chính xác.

Các công cụ được đặt tiền tố growthbook_ để chúng không bị mơ hồ khi client tải nhiều MCP server cùng lúc.

Cài đặt / chạy

npm install
npm run build

Trỏ MCP client của bạn tới entrypoint đã biên dịch:

{
  "mcpServers": {
    "growthbook": {
      "command": "node",
      "args": ["/absolute/path/to/growthbook-mcp/server/index.js"],
      "env": {
        "GB_API_KEY": "your_api_key_or_pat",
        "GB_API_URL": "https://api.growthbook.io"
      }
    }
  }
}

Hoặc chạy gói đã xuất bản:

npx @growthbook/mcp

Biến môi trường

Biến	Bắt buộc	Mặc định	Mục đích
GB_API_KEY	Có cho stdio; tùy chọn cho HTTP OAuth	—	Khóa API GrowthBook hoặc mã truy cập cá nhân
GB_API_URL	Không	https://api.growthbook.io	URL cơ sở API (tự lưu trữ) và issuer AS OAuth mặc định
GB_MCP_TRANSPORT	Không	stdio	stdio hoặc http
GB_MCP_PORT	Không	3333	Cổng lắng nghe HTTP (khi transport=http)
GB_MCP_HOST	Không	127.0.0.1	Host ràng buộc HTTP
GB_MCP_URL	Có cho HTTP	—	URL cơ sở MCP công khai được đóng dấu vào metadata tài nguyên OAuth (server từ chối khởi động ở chế độ HTTP nếu thiếu)
GB_OAUTH_ISSUER	Không	GB_API_URL	URL issuer AS OAuth GrowthBook
GB_HTTP_HEADER_*	Không	—	Header yêu cầu bổ sung (ví dụ GB_HTTP_HEADER_CF_ACCESS_TOKEN)
GB_SKILLS_ENABLED	Không	true	Đặt thành false / 0 để vô hiệu hóa công cụ kỹ năng

Chế độ HTTP + OAuth

OAUTH_AS_ENABLED=1  # on the GrowthBook API
GB_MCP_TRANSPORT=http GB_API_URL=http://localhost:3100 GB_MCP_PORT=3333 npm start

Client kết nối tới:

• http://127.0.0.1:3333/mcp — đầy đủ (kỹ năng + API đọc/ghi)
• http://127.0.0.1:3333/mcp/api — chỉ khả năng (growthbook_api_read + growthbook_api_write)

Các yêu cầu chưa xác thực nhận 401 với WWW-Authenticate trỏ tới /.well-known/oauth-protected-resource, nơi quảng cáo GrowthBook Authorization Server.

Trước khi xử lý MCP, server thăm dò GrowthBook REST (GET /api/v1/) với bearer. Một 401 từ lần thăm dò đó (hoặc sau đó từ công cụ API) tạo ra HTTP 401 với error="invalid_token" để MCP client có thể làm mới — thay vì hiển thị "This API key has expired" như một lỗi công cụ. Một 403 được coi là bearer được chấp nhận (từ chối quyền ≠ token không hợp lệ) để client không bị ép vào vòng lặp làm mới.

Chế độ chỉ khả năng

HTTP (khuyến nghị cho từ xa): trỏ client tới /mcp/api thay vì /mcp:

{
  "mcpServers": {
    "growthbook": {
      "url": "http://127.0.0.1:3333/mcp/api"
    }
  }
}

Đường dẫn	Công cụ
/mcp	growthbook_list_skills, growthbook_read_skill, growthbook_api_read, growthbook_api_write (trừ khi GB_SKILLS_ENABLED=false)
/mcp/api	growthbook_api_read, growthbook_api_write chỉ

stdio / toàn tiến trình: đặt env để kỹ năng không bao giờ được đăng ký:

"env": {
  "GB_API_KEY": "...",
  "GB_SKILLS_ENABLED": "false"
}

Khi kỹ năng bị vô hiệu hóa, chỉ các công cụ API đọc/ghi được đăng ký. growthbook_list_skills và growthbook_read_skill không được hiển thị.

Cách kỹ năng được đóng gói

npm run build   # tsc && bundle-skills

scripts/bundle-skills.mjs sao chép mọi skills/*/SKILL.md từ bản checkout kỹ năng chuẩn vào server/skills/<name>.md.

Giải quyết đường dẫn nguồn:

1. Biến env SKILLS_SRC (đường dẫn tới thư mục gốc repo kỹ năng), hoặc
2. ../skills (thư mục lân cận)

Repo kỹ năng vẫn là nguồn sự thật — gói này không bao giờ fork nội dung kỹ năng.

Sử dụng kỹ năng với công cụ API

Các kỹ năng được đóng gói vẫn hiển thị quy trình như:

gb-call GET /api/v1/projects
gb-call POST /api/v2/features ./payload.json

MCP server này không gọi ra gb-call. Ánh xạ GET → growthbook_api_read và POST/PUT/PATCH/DELETE → growthbook_api_write với cùng đường dẫn và chuỗi body JSON tùy chọn. Hướng dẫn server và đầu ra growthbook_read_skill bao gồm ghi chú cầu nối này.

Chi tiết công cụ

growthbook_api_read / growthbook_api_write

{ "path": "/api/v1/projects" }
{ "method": "POST", "path": "/api/v2/features", "body": "{\"id\":\"my-flag\",...}" }

• Đọc: chỉ GET (readOnlyHint: true)
• Ghi: POST | PUT | PATCH | DELETE (destructiveHint: true)
• Trả về body phản hồi thô trên 2xx
• Trên non-2xx, trả về lỗi có thể hành động (isError: true) bao gồm lỗi xác thực, gợi ý 404 tự lưu trữ và giới hạn tốc độ
• Đường dẫn tự do nhắm tới GrowthBook REST API

growthbook_list_skills / growthbook_read_skill

Chỉ được đăng ký khi GB_SKILLS_ENABLED không bị vô hiệu hóa. growthbook_read_skill trả về toàn bộ nội dung SKILL.md để agent có thể làm theo các bước quy trình và rào cản.

Phát triển

# Requires a sibling checkout at ../skills (or SKILLS_SRC)
npm install
npm run build
npm start

Chế độ HTTP độc lập

Theo mặc định, server chạy qua stdio. Đặt GB_MCP_TRANSPORT=http để chạy nó như một HTTP server độc lập hiển thị MCP tại /mcp (kỹ năng + công cụ API) và /mcp/api (chỉ khả năng), phía sau bề mặt tài nguyên được bảo vệ OAuth 2.0 (metadata RFC 9728 + WWW-Authenticate RFC 6750).

• GB_MCP_URL (bắt buộc ở chế độ HTTP) — URL cơ sở công khai của server. Nó được đóng dấu vào tài nguyên OAuth (audience) và metadata tài nguyên được bảo vệ, vì vậy nó không bao giờ được suy ra từ header yêu cầu. Server từ chối khởi động nếu thiếu.
• GB_MCP_PORT (mặc định 3333) và GB_MCP_HOST (mặc định 127.0.0.1).
• Các bearer đến được xác thực bằng cách thăm dò GrowthBook REST API; token bị từ chối nhận HTTP 401 + WWW-Authenticate để client có thể làm mới.

Chạy nó trên mạng đáng tin cậy hoặc ràng buộc với loopback. Đối với triển khai đa khách thuê hoặc công khai, đặt nó phía sau gateway/auth của riêng bạn.

Phát hành

Cắt một bản phát hành là có chủ đích: tăng phiên bản trong package.json, sau đó đẩy tag v* khớp:

git tag v2.0.0
git push origin v2.0.0

Commit được gắn tag đó (với kỹ năng đóng băng tại thời điểm cắt) xuất bản:

• @growthbook/mcp lên npm — bản tiền phát hành (phiên bản có -, ví dụ 2.0.0-beta.1) đi dưới dist-tag beta; phiên bản ổn định trở thành latest
• hình ảnh đa kiến trúc (amd64 + arm64) lên ghcr.io/growthbook/growthbook-mcp (:<version>, cộng :<major>, :<major>.<minor> và :latest cho bản phát hành ổn định)
• một mục trong registry MCP
• một GitHub Release

Cài đặt bản phát hành với npx @growthbook/mcp@<version> hoặc kéo ghcr.io/growthbook/growthbook-mcp:<version>.