GrowthBook MCP Server

GrowthBook MCP Thin

一个精简的 GrowthBook MCP 服务，包含四个工具：

工具	用途
growthbook_list_skills	列出顶层技能入口点（名称 + 描述）
growthbook_read_skill	返回已列出的技能或限定的子工作流（feature-flags 或 feature-flags/references/flag-create）
growthbook_api_read	经过身份验证的 GET 透传到 GrowthBook API
growthbook_api_write	经过身份验证的 POST/PUT/PATCH/DELETE 透传

能力位于 skills 仓库中，并在构建时打包。功能分为读与写 API 工具（没有按端点定制的格式化器），以便客户端能正确处理 readOnlyHint / destructiveHint。

工具名称以 growthbook_ 为前缀，这样当客户端加载了多个 MCP 服务时仍能保持无歧义。

Cursor 插件

从 Cursor Marketplace 安装 GrowthBook。该插件将 Cursor 连接到托管在 https://mcp.growthbook.io/mcp 的服务；首次调用工具时会打开 GrowthBook 登录以进行授权。可自托管 GrowthBook 的用户应按下文所述手动配置该服务。

该插件由 .cursor-plugin/plugin.json 和 mcp.json 定义。要在本地测试更改，请将仓库复制到 ~/.cursor/plugins/local/growthbook 并运行 Developer: Reload Window。

安装 / 运行

npm install
npm run build

将你的 MCP 客户端指向编译后的入口点：

{
  "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"
      }
    }
  }
}

或运行已发布的包：

npx @growthbook/mcp

环境变量

变量	是否必填	默认值	用途
GB_API_KEY	stdio 必填；HTTP OAuth 可选	—	GrowthBook API 密钥或个人访问令牌
GB_API_URL	否	https://api.growthbook.io	API 基础 URL（可自托管）以及默认 OAuth AS 颁发者
GB_MCP_TRANSPORT	否	stdio	stdio 或 http
GB_MCP_PORT	否	3333	HTTP 监听端口（当 transport=http 时）
GB_MCP_HOST	否	127.0.0.1	HTTP 绑定主机
GB_MCP_URL	HTTP 必填	—	写入 OAuth 资源元数据的公共 MCP 基础 URL（在 HTTP 模式下，若未设置服务器将拒绝启动）
GB_MCP_KEEP_ALIVE_TIMEOUT_MS	否	90000	HTTP 模式下的空闲 keep-alive 超时。必须大于前方任何负载均衡器的空闲超时，否则 LB 可能复用服务器已关闭的连接，导致请求以 502 失败
OPENAI_APPS_CHALLENGE_TOKEN	否	—	以纯文本形式在 /.well-known/openai-apps-challenge 提供，用于 OpenAI 插件域名验证（HTTP 模式）；未设置时该路由返回 404
GB_OAUTH_ISSUER	否	GB_API_URL	GrowthBook OAuth AS 颁发者 URL
GB_HTTP_HEADER_*	否	—	额外的请求头（例如 GB_HTTP_HEADER_CF_ACCESS_TOKEN）
GB_SKILLS_ENABLED	否	true	设为 false / 0 以禁用技能工具

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

客户端连接到：

• http://127.0.0.1:3333/mcp — 完整（技能 + API 读/写）
• http://127.0.0.1:3333/mcp/api — 仅功能（growthbook_api_read + growthbook_api_write）

未认证的请求会收到 401，并带有 WWW-Authenticate，指向 /.well-known/oauth-protected-resource，该地址通告 GrowthBook Authorization Server。

在处理 MCP 之前，服务器会使用 bearer 探测 GrowthBook REST（GET /api/v1/）。该探测返回的 401（或稍后来自 API 工具的 401）会产生 HTTP 401 并带有 error="invalid_token"，以便 MCP 客户端可以刷新——而不是将 "This API key has expired" 作为工具错误呈现。403 被视为 bearer 已被接受（权限被拒绝 ≠ 令牌无效），以免客户端被迫陷入刷新循环。

仅能力模式

HTTP（远程推荐）： 让客户端指向 /mcp/api 而不是 /mcp：

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

路径	工具
/mcp	growthbook_list_skills、growthbook_read_skill、growthbook_api_read、growthbook_api_write（除非 GB_SKILLS_ENABLED=false）
/mcp/api	仅 growthbook_api_read、growthbook_api_write

stdio / 进程级： 设置环境变量，使技能永不被注册：

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

当技能被禁用时，只有 API 读/写工具会被注册。growthbook_list_skills 和 growthbook_read_skill 不会暴露。

技能如何打包

npm run build   # tsc && bundle-skills

scripts/bundle-skills.mjs 从规范技能检出目录复制顶层技能树，保持结构不变：

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

源路径解析：

1. SKILLS_SRC 环境变量（技能仓库根目录的路径）
2. agent-skills.local.json — { "path": "../skills" }，相对于仓库根目录。已被 gitignore；复制 agent-skills.local.json.example
3. skills-src/ — CI 和 Docker 构建所 vendor 的内容

不存在隐式的同级查找。../skills 会解析为恰好位于该路径的任何内容，这会导致本地构建与 CI 构建所基于的提交悄然不一致。

CI、云部署和发布都会读取 agent-skills.lock.json 并检出 该确切的技能提交。要发布上游技能变更，请更新 锁文件中的提交。本地开发可通过 agent-skills.local.json 或 SKILLS_SRC 指向任何检出。

技能仓库始终是唯一事实来源——本包不维护技能内容的 分支。新技能会自动流入，除了 bundle-skills.mjs 中小区块名单里列出的那些。目前只有 gb-setup 被 屏蔽，因为它配置的是 gb-call shell 适配器而非 GrowthBook 本身。

单个技能的 scripts/ 目录不会被复制。相对 `references/foo.md` 链接会被重写为限定 `feature-flags/references/foo` 路径，以便 growthbook_read_skill 能解析 它们。

将技能与 API 工具配合使用

打包的技能仍将工作流显示为：

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

本 MCP 服务不会通过 shell 调用 gb-call。将 GET 映射到 growthbook_api_read，将 POST/PUT/PATCH/DELETE 映射到 growthbook_api_write，使用相同的路径和可选的 JSON 请求体字符串。服务指令和 growthbook_read_skill 输出都包含此桥接说明。

工具详情

growthbook_api_read / growthbook_api_write

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

• 读：仅 GET（readOnlyHint: true）
• 写：POST | PUT | PATCH | DELETE（destructiveHint: true）
• 在 2xx 时返回原始响应体
• 在非 2xx 时，返回可操作的错误（isError: true），涵盖认证失败、自托管 404 提示和速率限制
• 自由格式路径指向 GrowthBook REST API
• 每个请求都携带 MCP 使用头（参见使用遥测）

growthbook_list_skills / growthbook_read_skill

仅在 GB_SKILLS_ENABLED 未被禁用时注册。

• growthbook_list_skills 返回顶层技能入口点。一个条目可能包含完整工作流或指向子工作流的路由。
• growthbook_read_skill 接受列出的顶层名称或由已加载技能命名的限定子路径（feature-flags/references/flag-create），并返回完整的 markdown（工作流 + 护栏）。

使用遥测

此服务本身从不向任何地方发送遥测数据。相反，growthbook_api_read / growthbook_api_write 发出的每次 REST 调用都会包含一些请求头，告知其所通信的 GrowthBook 实例该调用来自此 MCP：

请求头	示例	内容
X-GB-MCP-Tool	growthbook_api_read	发出该调用的工具
X-GB-MCP-Version	2.2.0	此服务的版本
X-GB-MCP-Transport	stdio	stdio 或 http
X-GB-MCP-Client	cursor/1.2.3	来自 initialize 握手的 MCP 客户端名称/版本，或 HTTP 模式下的 User-Agent

GrowthBook 通过其现有的产品遥测记录这些信息，因此适用相同的控制方式。在可自托管实例上，在 GrowthBook 后端设置 DISABLE_TELEMETRY 会关闭此功能以及 GrowthBook 其余的遥测。较旧的 GrowthBook 版本会忽略这些请求头。技能工具（growthbook_list_skills / growthbook_read_skill）在本地提供，不发出任何请求，因此不会被追踪。

开发

git clone [email protected]: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

独立 HTTP 模式

默认情况下，此服务通过 stdio 运行。设置 GB_MCP_TRANSPORT=http 可将其作为独立 HTTP 服务运行，在 /mcp（技能 + API 工具）和 /mcp/api（仅能力）暴露 MCP，并置于 OAuth 2.0 受保护资源表面之后（RFC 9728 元数据 + RFC 6750 WWW-Authenticate）。

• GB_MCP_URL（HTTP 模式下必填）——服务的公共基础 URL。它会被写入 OAuth 资源（受众）和受保护资源元数据，因此绝不会从请求头中推导。缺少它时服务会拒绝启动。
• GB_MCP_PORT（默认 3333）和 GB_MCP_HOST（默认 127.0.0.1）。
• 传入的 bearer 通过探测 GrowthBook REST API 进行验证；被拒绝的令牌会收到 HTTP 401 + WWW-Authenticate，以便客户端可以刷新。

请在受信任的网络上运行它，或将其绑定到环回地址。对于多租户或公开部署，请在其前面加上你自己的网关/认证。

发布

发布是有意为之的：在 package.json 中提升版本号，运行 npm run sync-version（更新 manifest.json、server.json 和 .cursor-plugin/plugin.json），然后推送匹配的 v* 标签：

git tag v2.0.0
git push origin v2.0.0

该打标签的提交（技能在发布时冻结）会发布：

• @growthbook/mcp 到 npm——预发布版本（版本号带 -，例如 2.0.0-beta.1）归入 beta dist-tag；稳定版本成为 latest
• 一个多架构（amd64 + arm64）镜像到 ghcr.io/growthbook/growthbook-mcp（:<version>，以及稳定版本的 :<major>、:<major>.<minor> 和 :latest）
• MCP registry 中的一条记录
• 一个 GitHub Release

Cursor 插件不由 CI 发布：版本提升落地后，Cursor 会从默认分支重新审查该插件。

使用 npx @growthbook/mcp@<version> 安装某个发布版本，或拉取 ghcr.io/growthbook/growthbook-mcp:<version>。