GrowthBook MCP Server

GrowthBook MCP Thin

GrowthBook 向けの軽量 MCP サーバーで、次の 4 つのツールを提供します。

ツール	用途
growthbook_list_skills	最上位のスキルのエントリーポイント（名前＋説明）を一覧表示します
growthbook_read_skill	一覧にあるスキル、または指定された子ワークフロー（feature-flags または feature-flags/references/flag-create）を返します
growthbook_api_read	GrowthBook API への認証済み GET パススルーです
growthbook_api_write	認証済み POST/PUT/PATCH/DELETE パススルーです

専門知識は スキル リポジトリにあり、ビルド時にバンドルされます。機能は読み取り用と書き込み用の 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 リッスンポート（トランスポートが 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 モードでのアイドル状態のキープアライブタイムアウト。前段のロードバランサーのアイドルタイムアウトより大きくする必要があります。そうしないと、LB がサーバーによってすでに閉じられた接続を再利用し、リクエストが 502 で失敗する可能性があります
OPENAI_APPS_CHALLENGE_TOKEN	いいえ	—	OpenAI プラグインのドメイン検証用に /.well-known/openai-apps-challenge でプレーンテキストとして提供されます（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）

認証されていないリクエストには、GrowthBook Authorization Server を通知する /.well-known/oauth-protected-resource を指す WWW-Authenticate ヘッダー付きの 401 が返されます。

MCP リクエストを処理する前に、サーバーは bearer トークンを使って GrowthBook REST（GET /api/v1/）をプローブします。このプローブ（または後続の API ツール）から 401 が返された場合、MCP クライアントが更新できるように、サーバーは HTTP 401 と error="invalid_token" を返します。ツールエラーとして "This API key has expired" を表示することはありません。403 は bearer トークンを受け付けたものとして扱われます（権限拒否は無効なトークンとは異なるため）。そのため、クライアントが更新のループを強いられることはありません。

機能限定モード

HTTP（リモート利用に推奨）： クライアントの接続先を /mcp ではなく /mcp/api に設定します。

{
  "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" }。リポジトリのルートからの相対パスです。Git で無視されます。agent-skills.local.json.example をコピーしてください。
3. skills-src/ — CI と Docker ビルドで使用するパスです。

暗黙的に兄弟ディレクトリを検索することはありません。../skills は、そのパスにたまたま存在するものを指すため、ローカルビルドと CI がビルドするコミットの内容が、気付かないうちに食い違う可能性があります。

CI、クラウドへのデプロイ、リリースでは、すべて agent-skills.lock.json を読み込み、指定されたスキルのコミットをチェックアウトします。上流のスキルの変更を反映するには、ロックファイルのコミットを更新してください。ローカル開発では、agent-skills.local.json または SKILLS_SRC を使って、任意のチェックアウトを指定できます。

スキルリポジトリが引き続き信頼できる情報源となります。このパッケージでは、スキルの内容のフォークを管理しません。bundle-skills.mjs 内の小さなブロックリストに記載されているスキルを除き、新しいスキルは自動的に取り込まれます。現在ブロックされているのは gb-setup のみです。これは GrowthBook 自体ではなく、gb-call シェルアダプターを設定するためです。

スキルごとの scripts/ ディレクトリはコピーされません。相対パスの `references/foo.md` リンクは、growthbook_read_skill が解決できるように `feature-flags/references/foo` 形式のパスに書き換えられます。

API ツールでスキルを使用する

バンドルされたスキルでは、引き続きワークフローが次のように表示されます。

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

この MCP サーバーは gb-call をシェルから実行しません。GET は growthbook_api_read に、POST／PUT／PATCH／DELETE は同じパスと任意の JSON 本文文字列を指定して growthbook_api_write に対応付けてください。サーバーの指示と 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 以外の場合、認証エラー、セルフホスト環境での 404 に関するヒント、レート制限を含む、対処方法のわかるエラーを返します（isError: true）。
• 自由形式のパスは 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	初期化ハンドシェイクで渡された 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 を設定すると、OAuth 2.0 保護リソースの仕組み（RFC 9728 メタデータおよび RFC 6750 WWW-Authenticate）の背後で、/mcp（スキル＋API ツール）と /mcp/api（機能のみ）に MCP を公開する、スタンドアロンの HTTP サーバーとして実行されます。

• GB_MCP_URL（HTTP モードでは必須）— サーバーの公開ベース URL です。OAuth リソース（audience）と保護リソースのメタデータに設定され、リクエストヘッダーから導出されることはありません。この値を指定しないと、サーバーは起動を拒否します。
• 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

タグ付けされたコミット（リリース作成時点でスキルが固定されます）から、次のものが公開されます。

• npm の @growthbook/mcp — プレリリース（2.0.0-beta.1 など、バージョンに - が含まれるもの）は beta dist-tag で公開され、安定版は latest になります
• マルチアーキテクチャ（amd64 ＋ arm64）イメージを ghcr.io/growthbook/growthbook-mcp に公開（安定版リリースでは :<version> に加えて :<major>、:<major>.<minor>、:latest）
• MCP レジストリーのエントリー
• GitHub リリース

Cursor プラグインは CI では公開されません。バージョン更新が反映された後、Cursor がデフォルトブランチ上のプラグインを再審査します。

npx @growthbook/mcp@<version> でリリースをインストールするか、ghcr.io/growthbook/growthbook-mcp:<version> をプルしてください。