@growthbook/mcp weekly downloads statistics

GrowthBook MCP Thin

A thin MCP server for GrowthBook with four tools:

Tool	Purpose
growthbook_list_skills	List top-level skill entry points (name + description)
growthbook_read_skill	Return a listed skill or qualified child workflow (feature-flags or feature-flags/references/flag-create)
growthbook_api_read	Authenticated GET passthrough to the GrowthBook API
growthbook_api_write	Authenticated 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

Variable	Required	Default	Purpose
GB_API_KEY	Yes for stdio; optional for HTTP OAuth	—	GrowthBook API key or personal access token
GB_API_URL	No	https://api.growthbook.io	API base URL (self-hosted) and default OAuth AS issuer
GB_MCP_TRANSPORT	No	stdio	stdio or http
GB_MCP_PORT	No	3333	HTTP listen port (when transport=http)
GB_MCP_HOST	No	127.0.0.1	HTTP bind host
GB_MCP_URL	Yes 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_MS	No	90000	Idle 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_ISSUER	No	GB_API_URL	GrowthBook OAuth AS issuer URL
GB_HTTP_HEADER_*	No	—	Extra request headers (e.g. GB_HTTP_HEADER_CF_ACCESS_TOKEN)
GB_SKILLS_ENABLED	No	true	Set 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"
    }
  }
}

Path	Tools
/mcp	growthbook_list_skills, growthbook_read_skill, growthbook_api_read, growthbook_api_write (unless GB_SKILLS_ENABLED=false)
/mcp/api	growthbook_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
```…