GrowthBook

GrowthBook MCP Thin

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

Công cụ	Mục đích
growthbook_list_skills	Liệt kê các điểm vào kỹ năng cấp cao nhất (tên + mô tả)
growthbook_read_skill	Trả về một kỹ năng đã liệt kê hoặc quy trình con đủ điều kiện (feature-flags hoặc feature-flags/references/flag-create)
growthbook_api_read	Chuyển tiếp GET đã xác thực tới API GrowthBook
growthbook_api_write	Chuyển tiếp POST/PUT/PATCH/DELETE đã xác thực

Năng lực nằm trong kho skills và được đóng gói tại thời điểm xây dựng. Khả năng được chia thành các công cụ API đọc và ghi (không có định dạng theo từng điểm cuối) để máy khách 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 máy khách có nhiều máy chủ MCP được tải.

Plugin Cursor

Cài đặt GrowthBook từ Cursor Marketplace. Plugin kết nối Cursor với máy chủ lưu trữ tại https://mcp.growthbook.io/mcp; lệnh gọi công cụ đầu tiên sẽ mở đăng nhập GrowthBook để ủy quyền. Người dùng GrowthBook tự lưu trữ nên cấu hình máy chủ thủ công như mô tả bên dưới.

Plugin được định nghĩa bởi .cursor-plugin/plugin.json và mcp.json. Để kiểm tra thay đổi cục bộ, sao chép kho vào ~/.cursor/plugins/local/growthbook và chạy Developer: Reload Window.

Cài đặt / chạy

npm install
npm run build

Trỏ máy khách MCP của bạn vào điểm vào đã 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ã thông báo truy cập cá nhân
GB_API_URL	Không	https://api.growthbook.io	URL cơ sở API (tự lưu trữ) và nhà phát hành AS OAuth mặc định
GB_MCP_TRANSPORT	Không	stdio	stdio hoặc http
GB_MCP_PORT	Không	3333	Cổng nghe HTTP (khi transport=http)
GB_MCP_HOST	Không	127.0.0.1	Máy chủ liên kết HTTP
GB_MCP_URL	Có cho HTTP	—	URL cơ sở MCP công khai được đóng dấu vào siêu dữ liệu tài nguyên OAuth (máy chủ từ chối khởi động ở chế độ HTTP nếu thiếu)
GB_MCP_KEEP_ALIVE_TIMEOUT_MS	Không	90000	Thời gian chờ giữ kết nối nhàn rỗi ở chế độ HTTP. Phải vượt quá thời gian chờ nhàn rỗi của bất kỳ bộ cân bằng tải nào phía trước, nếu không LB có thể tái sử dụng kết nối mà máy chủ đã đóng và yêu cầu thất bại với mã 502
OPENAI_APPS_CHALLENGE_TOKEN	Không	—	Được phục vụ dưới dạng văn bản thuần tại /.well-known/openai-apps-challenge để xác minh miền plugin OpenAI (chế độ HTTP); tuyến trả về 404 khi không được đặt
GB_OAUTH_ISSUER	Không	GB_API_URL	URL nhà phát hành AS OAuth GrowthBook
GB_HTTP_HEADER_*	Không	—	Tiêu đề 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ác 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

Máy khách kết nối tới:

• http://127.0.0.1:3333/mcp — đầy đủ (kỹ năng + đọc/ghi API)
• 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 Máy chủ ủy quyền GrowthBook.

Trước khi xử lý MCP, máy chủ thăm dò GrowthBook REST (GET /api/v1/) với bearer. Một 401 từ lần thăm dò đó (hoặc sau đó từ một công cụ API) tạo ra HTTP 401 với error="invalid_token" để máy khách MCP 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 ≠ mã thông báo không hợp lệ) để máy khách không bị buộc vào vòng lặp làm mới.

Chế độ chỉ khả năng

HTTP (khuyến nghị cho từ xa): trỏ máy khách vào /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 quy 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ụ đọc/ghi API đượ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 cây kỹ năng cấp cao nhất từ bản kiểm tra kỹ năng chuẩn, giữ nguyên cấu trúc:

skills/<skill>/SKILL.md                   → server/skills/<skill>/SKILL.md
skills/<skill>/references/<workflow>.md   → server/skills/<skill>/references/<workflow>.md

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

1. Biến env SKILLS_SRC (đường dẫn tới gốc kho kỹ năng)
2. agent-skills.local.json — { "path": "../skills" }, tương đối với gốc kho. Bị gitignore; sao chép agent-skills.local.json.example
3. skills-src/ — những gì CI và bản dựng Docker cung cấp

Không có tra cứu ngang hàng ngầm. ../skills phân giải thành bất cứ thứ gì tại đường dẫn đó, điều này khiến bản dựng cục bộ âm thầm không khớp với cam kết mà CI xây dựng từ đó.

CI, triển khai đám mây và bản phát hành đều đọc agent-skills.lock.json và kiểm tra chính xác cam kết kỹ năng đó. Để gửi thay đổi kỹ năng thượng nguồn, hãy cập nhật cam kết trong tệp khóa. Phát triển cục bộ có thể trỏ vào bất kỳ bản kiểm tra nào với agent-skills.local.json hoặc SKILLS_SRC.

Kho kỹ năng vẫn là nguồn sự thật — gói này không duy trì bản sao nội dung kỹ năng. Kỹ năng mới tự động chảy qua, ngoại trừ những kỹ năng được nêu tên trong danh sách chặn nhỏ trong bundle-skills.mjs. Hiện chỉ gb-setup bị chặn vì nó cấu hình bộ điều hợp shell gb-call thay vì GrowthBook chính nó.

Các thư mục scripts/ theo từng kỹ năng không được sao chép. Các liên kết tương đối `references/foo.md` được viết lại thành `feature-flags/references/foo` paths so growthbook_read_skill có thể phân giải chúng.

Sử dụng kỹ năng với các 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

Máy chủ MCP 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 thân JSON tùy chọn. Hướng dẫn máy chủ 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ề thân phản hồi thô trên 2xx
• Trên không phải 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
• Mỗi yêu cầu mang tiêu đề sử dụng MCP (xem Số liệu sử dụng)

growthbook_list_skills / growthbook_read_skill

Chỉ được đăng ký khi GB_SKILLS_ENABLED không bị vô hiệu hóa.

• growthbook_list_skills trả về các điểm vào kỹ năng cấp cao nhất. Một điểm vào có thể chứa quy trình hoàn chỉnh hoặc định tuyến tới quy trình con.
• growthbook_read_skill chấp nhận tên cấp cao nhất đã liệt kê hoặc đường dẫn con đủ điều kiện được đặt tên bởi kỹ năng đã tải (feature-flags/references/flag-create) và trả về markdown đầy đủ (quy trình + lan can).

Số liệu sử dụng

Máy chủ này không bao giờ gửi số liệu từ xa ở bất kỳ đâu. Thay vào đó, mỗi lệnh gọi REST được thực hiện bởi growthbook_api_read / growthbook_api_write bao gồm các tiêu đề cho phiên bản GrowthBook biết rằng lệnh gọi đến từ MCP:

Tiêu đề	Ví dụ	Nội dung
X-GB-MCP-Tool	growthbook_api_read	Công cụ đã thực hiện lệnh gọi
X-GB-MCP-Version	2.2.0	Phiên bản của máy chủ này
X-GB-MCP-Transport	stdio	stdio hoặc http
X-GB-MCP-Client	cursor/1.2.3	Tên/phiên bản máy khách MCP từ bắt tay khởi tạo, hoặc User-Agent của nó ở chế độ HTTP

GrowthBook ghi lại những điều này thông qua số liệu sản phẩm hiện có của nó, vì vậy các kiểm soát tương tự được áp dụng. Trên phiên bản tự lưu trữ, đặt DISABLE_TELEMETRY trên back-end GrowthBook sẽ tắt tính năng này cùng với phần còn lại của số liệu GrowthBook. Các phiên bản GrowthBook cũ hơn bỏ qua các tiêu đề. Các công cụ kỹ năng (growthbook_list_skills / growthbook_read_skill) được phục vụ cục bộ và không thực hiện yêu cầu, vì vậy chúng không được theo dõi.

Phát triển

git clone git@github.com:growthbook/skills.git ../skills
cp agent-skills.local.json.example agent-skills.local.json  # edit if not at ../skills

npm install
npm run build
npm start

Chế độ HTTP độc lập

Theo mặc định, máy chủ chạy qua stdio. Đặt GB_MCP_TRANSPORT=http để chạy nó như một máy chủ HTTP độ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 (siêu dữ liệu RFC 9728 + WWW-Authenticate RFC 6750).

• GB_MCP_URL (bắt buộc ở chế độ HTTP) — URL cơ sở công khai của máy chủ. Nó được đóng dấu vào tài nguyên OAuth (đối tượng) và siêu dữ liệu tài nguyên được bảo vệ, vì vậy nó không bao giờ được suy ra từ tiêu đề yêu cầu. Máy chủ từ chối khởi động nếu thiếu nó.
• 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ò API REST GrowthBook; mã thông báo bị từ chối nhận HTTP 401 + WWW-Authenticate để máy khách có thể làm mới.

Chạy nó trên mạng đáng tin cậy hoặc liên kết với loopback. Đối với triển khai đa khách thuê hoặc công khai, hãy đặt nó phía sau cổng/xác thực của riêng bạn.

Bản phát hành

Cắt bản phát hành là có chủ đích: tăng phiên bản trong package.json, chạy npm run sync-version (cập nhật manifest.json, server.json và .cursor-plugin/plugin.json), sau đó đẩy thẻ v* khớp:

git tag v2.0.0
git push origin v2.0.0

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

• @growthbook/mcp lên npm — bản phát hành trước (phiên bản có -, ví dụ: 2.0.0-beta.1) đi dưới thẻ phân phối 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 sổ đăng ký MCP
• một Bản phát hành GitHub

Plugin Cursor không được xuất bản bởi CI: Cursor xem xét lại plugin từ nhánh mặc định sau khi tăng phiên bản được áp dụng.

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>.