@growthbook/mcp

中文文档
2.2.0发布于 2026/10/07MITES Module构建来源已验证近 30 天下载 3.2万

Thin MCP server for GrowthBook — skill loader + authenticated API passthrough

原始使用文档
文档目录13 节
  1. Install / run
  2. Environment variables
  3. HTTP + OAuth mode
  4. Capability-only mode
  5. How skills are bundled
  6. Using skills with the API tools
  7. Tools detail
  8. growthbook_api_read / growthbook_api_write
  9. growthbook_list_skills / growthbook_read_skill
  10. Usage telemetry
  11. Development
  12. Standalone HTTP mode
  13. Releases

GrowthBook MCP Thin

A thin MCP server for GrowthBook with four tools:

ToolPurpose
growthbook_list_skillsList top-level skill entry points (name + description)
growthbook_read_skillReturn a listed skill or qualified child workflow (feature-flags or feature-flags/references/flag-create)
growthbook_api_readAuthenticated GET passthrough to the GrowthBook API
growthbook_api_writeAuthenticated POST/PUT/PATCH/DELETE passthrough

Competence lives in the skills repo and is bundled at build time. Capability is split into read vs write API tools (no per-endpoint formatters) so clients can honor readOnlyHint / destructiveHint correctly.

Tools are prefixed with growthbook_ so they stay unambiguous when a client has multiple MCP servers loaded.

Install / run

npm install
npm run build

Point your MCP client at the compiled entrypoint:

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

Or run the published package:

npx @growthbook/mcp

Environment variables

VariableRequiredDefaultPurpose
GB_API_KEYYes for stdio; optional for HTTP OAuth—GrowthBook API key or personal access token
GB_API_URLNohttps://api.growthbook.ioAPI base URL (self-hosted) and default OAuth AS issuer
GB_MCP_TRANSPORTNostdiostdio or http
GB_MCP_PORTNo3333HTTP listen port (when transport=http)
GB_MCP_HOSTNo127.0.0.1HTTP bind host
GB_MCP_URLYes for HTTP—Public MCP base URL stamped into OAuth resource metadata (server refuses to start in HTTP mode without it)
GB_MCP_KEEP_ALIVE_TIMEOUT_MSNo90000Idle keep-alive timeout in HTTP mode. Must exceed the idle timeout of any load balancer in front, or the LB can reuse a connection the server has already closed and the request fails with a 502
GB_OAUTH_ISSUERNoGB_API_URLGrowthBook OAuth AS issuer URL
GB_HTTP_HEADER_*No—Extra request headers (e.g. GB_HTTP_HEADER_CF_ACCESS_TOKEN)
GB_SKILLS_ENABLEDNotrueSet to false / 0 to disable skill tools

HTTP + OAuth mode

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

Clients connect to:

  • http://127.0.0.1:3333/mcp — full (skills + API read/write)
  • http://127.0.0.1:3333/mcp/api — capability-only (growthbook_api_read + growthbook_api_write)

Unauthenticated requests receive 401 with WWW-Authenticate pointing at /.well-known/oauth-protected-resource, which advertises the GrowthBook Authorization Server.

Before handling MCP, the server probes GrowthBook REST (GET /api/v1/) with the bearer. A 401 from that probe (or later from an API tool) yields HTTP 401 with error="invalid_token" so the MCP client can refresh — instead of surfacing "This API key has expired" as a tool error. A 403 is treated as an accepted bearer (permission denied ≠ invalid token) so clients are not forced into a refresh loop.

Capability-only mode

HTTP (recommended for remote): point the client at /mcp/api instead of /mcp:

{
  "mcpServers": {
    "growthbook": {
      "url": "http://127.0.0.1:3333/mcp/api"
    }
  }
}
PathTools
/mcpgrowthbook_list_skills, growthbook_read_skill, growthbook_api_read, growthbook_api_write (unless GB_SKILLS_ENABLED=false)
/mcp/apigrowthbook_api_read, growthbook_api_write only

stdio / process-wide: set env so skills are never registered:

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

When skills are disabled, only the API read/write tools are registered. growthbook_list_skills and growthbook_read_skill are not exposed.

How skills are bundled

npm run build   # tsc && bundle-skills

scripts/bundle-skills.mjs copies the top-level skill tree from the canonical skills checkout, preserving structure:

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

Source path resolution:

  1. SKILLS_SRC env var (path to the skills repo root)
  2. agent-skills.local.json — { "path": "../skills" }, relative to the repo root. Gitignored; copy agent-skills.local.json.example
  3. skills-src/ — what CI and the Docker build vendor

There is no implicit sibling lookup. ../skills resolves to whatever happens to be at that path, which makes a local build silently disagree with the commit CI builds from.

CI, cloud deploys, and releases all read agent-skills.lock.json and check out that exact skills commit. To ship upstream skill changes, update the commit in the lock file. Local development can point at any checkout with agent-skills.local.json or SKILLS_SRC.

The skills repo stays the source of truth — this package does not maintain a fork of skill content. New skills flow through automatically, except those named in the small blocklist in bundle-skills.mjs. Currently only gb-setup is blocked because it configures the gb-call shell adapter rather than GrowthBook itself.

Per-skill scripts/ directories are not copied. Relative `references/foo.md` links are rewritten to qualified `feature-flags/references/foo` paths so growthbook_read_skill can resolve them.

Using skills with the API tools

Bundled skills still show workflows as:

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

This MCP server does not shell out to gb-call. Map GET → growthbook_api_read and POST/PUT/PATCH/DELETE → growthbook_api_write with the same path and optional JSON body string. Server instructions and growthbook_read_skill output include this bridge note.

Tools detail

growthbook_api_read / growthbook_api_write

{ "path": "/api/v1/projects" }
{ "method": "POST", "path": "/api/v2/features", "body": "{\"id\":\"my-flag\",...}" }
  • Read: GET only (readOnlyHint: true)
  • Write: POST | PUT | PATCH | DELETE (destructiveHint: true)
  • Returns raw response body on 2xx
  • On non-2xx, returns an actionable error (isError: true) covering auth failures, self-hosted 404 hints, and rate limits
  • Freeform paths target the GrowthBook REST API
  • Each request carries MCP usage headers (see Usage telemetry)

growthbook_list_skills / growthbook_read_skill

Only registered when GB_SKILLS_ENABLED is not disabled.

  • growthbook_list_skills returns top-level skill entry points. An entry may contain a complete workflow or route to child workflows.
  • growthbook_read_skill accepts a listed top-level name or a qualified child path named by a loaded skill (feature-flags/references/flag-create) and returns the full markdown (workflow + guardrails).

Usage telemetry

This server never sends telemetry anywhere itself. Instead, every REST call made by growthbook_api_read / growthbook_api_write includes headers that tell the GrowthBook instance it's talking to that the call came from the MCP:

HeaderExampleContents
X-GB-MCP-Toolgrowthbook_api_readThe tool that made the call
X-GB-MCP-Version2.2.0This server's version
X-GB-MCP-Transportstdiostdio or http
X-GB-MCP-Clientcursor/1.2.3The MCP client's name/version from the initialize handshake, or its User-Agent in HTTP mode

GrowthBook records these through its existing product telemetry, so the same controls apply. On a self-hosted instance, setting DISABLE_TELEMETRY on the GrowthBook back-end turns this off along with the rest of GrowthBook's telemetry. Older GrowthBook versions ignore the headers. Skill tools (growthbook_list_skills / growthbook_read_skill) are served locally and make no requests, so they aren't tracked.

Development

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

Standalone HTTP mode

By default the server runs over stdio. Set GB_MCP_TRANSPORT=http to run it as a standalone HTTP server that exposes MCP at /mcp (skills + API tools) and /mcp/api (capability-only), behind an OAuth 2.0 protected-resource surface (RFC 9728 metadata + RFC 6750 WWW-Authenticate).

  • GB_MCP_URL (required in HTTP mode) — the server's public base URL. It is stamped into the OAuth resource (audience) and the protected-resource metadata, so it is never derived from request headers. The server refuses to start without it.
  • GB_MCP_PORT (default 3333) and GB_MCP_HOST (default 127.0.0.1).
  • Incoming bearers are validated by probing the GrowthBook REST API; a rejected token gets HTTP 401 + WWW-Authenticate so the client can refresh.

Run it on a trusted network or bound to loopback. For a multi-tenant or public deployment, front it with your own gateway/auth.

Releases

Cutting a release is deliberate: bump the version in package.json, then push a matching v* tag:

git tag v2.0.0
git push origin v2.0.0

That tagged commit (with skills frozen at cut time) publishes:

  • @growthbook/mcp to npm — prereleases (versions with a -, e.g. 2.0.0-beta.1) go under the beta dist-tag; stable versions become latest
  • a multi-arch (amd64 + arm64) image to ghcr.io/growthbook/growthbook-mcp (:<version>, plus :<major>, :<major>.<minor>, and :latest for stable releases)
  • an entry in the MCP registry
  • a GitHub Release

Install a release with npx @growthbook/mcp@<version> or pull ghcr.io/growthbook/growthbook-mcp:<version>.

版本与发布记录

@growthbook/mcp 共发布 24 个版本,首次发布于 2025/05/16;过去 12 个月发布了 15 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
2.2.0latest2026/10/071 个月前
2.1.02026/08/123 个月前
2.0.02026/07/313 个月前
1.8.12026/03/108 个月前
1.8.02026/03/098 个月前
1.7.02026/03/078 个月前

关于 @growthbook/mcp 的常见问题

@growthbook/mcp 是什么?

Thin MCP server for GrowthBook — skill loader + authenticated API passthrough

如何安装 @growthbook/mcp?

在项目目录运行 npm install @growthbook/mcp,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 mcp,可以用 npx mcp 直接运行。

@growthbook/mcp 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/growthbook__mcp 是否存在。

@growthbook/mcp 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@growthbook/mcp 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=18。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@growthbook/mcp 可以商用吗?

@growthbook/mcp 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@growthbook/mcp 的下载量有多少?

根据 npm 官方下载统计,@growthbook/mcp 在 2026/10/17 – 2026/11/15 这 30 天内被下载 32,172 次,日均约 1,072 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@growthbook/mcp 还在维护吗?

最新版本 2.2.0 发布于 2026/10/07(1 个月前);至今共发布 24 个版本,其中过去 12 个月发布了 15 个;首次发布于 2025/05/16。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。