GrowthBook

GrowthBook MCP Thin

Ein schlanker MCP-Server für GrowthBook mit vier Tools:

Tool	Zweck
growthbook_list_skills	Listet die wichtigsten Skill-Einstiegspunkte auf (Name + Beschreibung)
growthbook_read_skill	Gibt einen gelisteten Skill oder einen qualifizierten untergeordneten Workflow zurück (feature-flags oder feature-flags/references/flag-create)
growthbook_api_read	Authentifizierter GET-Passthrough zur GrowthBook-API
growthbook_api_write	Authentifizierter POST/PUT/PATCH/DELETE-Passthrough

Die Kompetenz liegt im skills-Repository und wird zur Build-Zeit gebündelt. Die Funktionalität ist in Lese- vs. Schreib-API-Tools aufgeteilt (keine Per-Endpunkt-Formatierer), sodass Clients readOnlyHint / destructiveHint korrekt berücksichtigen können.

Tools sind mit growthbook_ präfixiert, damit sie eindeutig bleiben, wenn ein Client mehrere MCP-Server geladen hat.

Cursor-Plugin

Installieren Sie GrowthBook aus dem Cursor Marketplace. Das Plugin verbindet Cursor mit dem gehosteten Server unter https://mcp.growthbook.io/mcp; der erste Tool-Aufruf öffnet eine GrowthBook-Anmeldung zur Autorisierung. Selbst gehostete GrowthBook-Nutzer sollten den Server wie unten beschrieben manuell konfigurieren.

Das Plugin wird durch .cursor-plugin/plugin.json und mcp.json definiert. Um Änderungen lokal zu testen, kopieren Sie das Repository nach ~/.cursor/plugins/local/growthbook und führen Sie Developer: Reload Window aus.

Installation / Ausführung

npm install
npm run build

Weisen Sie Ihren MCP-Client auf den kompilierten Einstiegspunkt:

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

Oder führen Sie das veröffentlichte Paket aus:

npx @growthbook/mcp

Umgebungsvariablen

Variable	Erforderlich	Standard	Zweck
GB_API_KEY	Ja für stdio; optional für HTTP-OAuth	—	GrowthBook-API-Schlüssel oder persönliches Zugriffstoken
GB_API_URL	Nein	https://api.growthbook.io	API-Basis-URL (selbst gehostet) und Standard-OAuth-AS-Issuer
GB_MCP_TRANSPORT	Nein	stdio	stdio oder http
GB_MCP_PORT	Nein	3333	HTTP-Listen-Port (wenn transport=http)
GB_MCP_HOST	Nein	127.0.0.1	HTTP-Bind-Host
GB_MCP_URL	Ja für HTTP	—	Öffentliche MCP-Basis-URL, die in die OAuth-Ressourcenmetadaten eingestempelt wird (der Server weigert sich, im HTTP-Modus ohne sie zu starten)
GB_MCP_KEEP_ALIVE_TIMEOUT_MS	Nein	90000	Leerlauf-Timeout im HTTP-Modus. Muss das Leerlauf-Timeout eines vorgeschalteten Load Balancers überschreiten, sonst kann der LB eine Verbindung wiederverwenden, die der Server bereits geschlossen hat, und die Anfrage schlägt mit 502 fehl
OPENAI_APPS_CHALLENGE_TOKEN	Nein	—	Wird als Klartext unter /.well-known/openai-apps-challenge für die OpenAI-Plugin-Domain-Verifizierung ausgeliefert (HTTP-Modus); die Route gibt 404 zurück, wenn nicht gesetzt
GB_OAUTH_ISSUER	Nein	GB_API_URL	GrowthBook-OAuth-AS-Issuer-URL
GB_HTTP_HEADER_*	Nein	—	Zusätzliche Anfrage-Header (z. B. GB_HTTP_HEADER_CF_ACCESS_TOKEN)
GB_SKILLS_ENABLED	Nein	true	Auf false / 0 setzen, um Skill-Tools zu deaktivieren

HTTP + OAuth-Modus

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 verbinden sich mit:

• http://127.0.0.1:3333/mcp — vollständig (Skills + API-Lesen/Schreiben)
• http://127.0.0.1:3333/mcp/api — nur Funktionalität (growthbook_api_read + growthbook_api_write)

Nicht authentifizierte Anfragen erhalten 401 mit WWW-Authenticate, das auf /.well-known/oauth-protected-resource verweist, welches den GrowthBook-Autorisierungsserver bewirbt.

Bevor der Server MCP verarbeitet, prüft er die GrowthBook-REST-API (GET /api/v1/) mit dem Bearer-Token. Ein 401 von dieser Prüfung (oder später von einem API-Tool) führt zu HTTP 401 mit error="invalid_token", damit der MCP-Client aktualisieren kann — anstatt "This API key has expired" als Tool-Fehler anzuzeigen. Ein 403 wird als akzeptiertes Bearer-Token behandelt (Zugriff verweigert ≠ ungültiges Token), sodass Clients nicht in eine Aktualisierungsschleife gezwungen werden.

Nur-Funktionalitäts-Modus

HTTP (empfohlen für Remote): Weisen Sie den Client auf /mcp/api statt /mcp:

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

Pfad	Tools
/mcp	growthbook_list_skills, growthbook_read_skill, growthbook_api_read, growthbook_api_write (außer GB_SKILLS_ENABLED=false)
/mcp/api	growthbook_api_read, growthbook_api_write nur

stdio / prozessweit: Setzen Sie die Umgebungsvariablen so, dass Skills nie registriert werden:

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

Wenn Skills deaktiviert sind, werden nur die API-Lese-/Schreib-Tools registriert. growthbook_list_skills und growthbook_read_skill werden nicht bereitgestellt.

Wie Skills gebündelt werden

npm run build   # tsc && bundle-skills

scripts/bundle-skills.mjs kopiert den Skill-Baum der obersten Ebene aus dem kanonischen Skills-Checkout und bewahrt die Struktur:

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

Auflösung des Quellpfads:

1. SKILLS_SRC Umgebungsvariable (Pfad zum Skills-Repository-Root)
2. agent-skills.local.json — { "path": "../skills" }, relativ zum Repository-Root. Gitignored; kopieren Sie agent-skills.local.json.example
3. skills-src/ — was CI und der Docker-Build verwenden

Es gibt keine implizite Geschwister-Suche. ../skills löst zu dem auf, was sich zufällig an diesem Pfad befindet, wodurch ein lokaler Build stillschweigend von dem Commit abweichen kann, den CI erstellt.

CI, Cloud-Deployments und Releases lesen alle agent-skills.lock.json und checken genau diesen Skills-Commit aus. Um Upstream-Skill-Änderungen auszuliefern, aktualisieren Sie den Commit in der Lock-Datei. Die lokale Entwicklung kann mit agent-skills.local.json oder SKILLS_SRC auf jeden Checkout zeigen.

Das Skills-Repository bleibt die Quelle der Wahrheit — dieses Paket pflegt keinen Fork des Skill-Inhalts. Neue Skills fließen automatisch ein, außer denen, die in der kleinen Blocklist in bundle-skills.mjs genannt sind. Derzeit ist nur gb-setup blockiert, weil es den gb-call-Shell-Adapter konfiguriert und nicht GrowthBook selbst.

Pro-Skill-scripts/-Verzeichnisse werden nicht kopiert. Relative `references/foo.md`-Links werden in qualifizierte `feature-flags/references/foo` paths so growthbook_read_skill umgeschrieben, damit sie aufgelöst werden können.

Skills mit den API-Tools verwenden

Gebündelte Skills zeigen Workflows weiterhin als:

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

Dieser MCP-Server führt keine Shell-Aufrufe an gb-call aus. Ordnen Sie GET → growthbook_api_read und POST/PUT/PATCH/DELETE → growthbook_api_write mit demselben Pfad und optionalem JSON-Body-String zu. Server-Anweisungen und growthbook_read_skill-Ausgabe enthalten diesen Brücken-Hinweis.

Tool-Details

growthbook_api_read / growthbook_api_write

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

• Lesen: Nur GET (readOnlyHint: true)
• Schreiben: POST | PUT | PATCH | DELETE (destructiveHint: true)
• Gibt den rohen Antwort-Body bei 2xx zurück
• Bei Nicht-2xx wird ein umsetzbarer Fehler zurückgegeben (isError: true), der Authentifizierungsfehler, Selbst-Hosting-404-Hinweise und Ratenlimits abdeckt
• Freiform-Pfade zielen auf die GrowthBook-REST-API
• Jede Anfrage enthält MCP-Nutzungs-Header (siehe Nutzungstelemetrie)

growthbook_list_skills / growthbook_read_skill

Nur registriert, wenn GB_SKILLS_ENABLED nicht deaktiviert ist.

• growthbook_list_skills gibt die Skill-Einstiegspunkte der obersten Ebene zurück. Ein Eintrag kann einen vollständigen Workflow enthalten oder zu untergeordneten Workflows führen.
• growthbook_read_skill akzeptiert einen gelisteten Namen der obersten Ebene oder einen qualifizierten untergeordneten Pfad, der von einem geladenen Skill benannt wird (feature-flags/references/flag-create), und gibt das vollständige Markdown zurück (Workflow + Schutzmaßnahmen).

Nutzungstelemetrie

Dieser Server sendet selbst nie Telemetrie. Stattdessen enthält jeder REST-Aufruf von growthbook_api_read / growthbook_api_write Header, die der GrowthBook-Instanz mitteilen, dass der Aufruf vom MCP stammt:

Header	Beispiel	Inhalt
X-GB-MCP-Tool	growthbook_api_read	Das Tool, das den Aufruf ausgeführt hat
X-GB-MCP-Version	2.2.0	Die Version dieses Servers
X-GB-MCP-Transport	stdio	stdio oder http
X-GB-MCP-Client	cursor/1.2.3	Der Name/die Version des MCP-Clients aus dem Initialize-Handshake oder dessen User-Agent im HTTP-Modus

GrowthBook zeichnet diese über seine bestehende Produkttelemetrie auf, sodass dieselben Steuerungen gelten. Bei einer selbst gehosteten Instanz deaktiviert das Setzen von DISABLE_TELEMETRY auf dem GrowthBook-Backend dies zusammen mit der übrigen GrowthBook-Telemetrie. Ältere GrowthBook-Versionen ignorieren die Header. Skill-Tools (growthbook_list_skills / growthbook_read_skill) werden lokal bedient und machen keine Anfragen, daher werden sie nicht erfasst.

Entwicklung

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

Eigenständiger HTTP-Modus

Standardmäßig läuft der Server über stdio. Setzen Sie GB_MCP_TRANSPORT=http, um ihn als eigenständigen HTTP-Server auszuführen, der MCP unter /mcp (Skills + API-Tools) und /mcp/api (nur Funktionalität) bereitstellt, hinter einer OAuth-2.0-geschützten Ressourcenoberfläche (RFC-9728-Metadaten + RFC-6750 WWW-Authenticate).

• GB_MCP_URL (erforderlich im HTTP-Modus) — die öffentliche Basis-URL des Servers. Sie wird in die OAuth-Ressource (Audience) und die Metadaten der geschützten Ressource eingestempelt, sodass sie nie aus Anfrage-Headern abgeleitet wird. Der Server weigert sich, ohne sie zu starten.
• GB_MCP_PORT (Standard 3333) und GB_MCP_HOST (Standard 127.0.0.1).
• Eingehende Bearer-Tokens werden durch Prüfung der GrowthBook-REST-API validiert; ein abgelehntes Token erhält HTTP 401 + WWW-Authenticate, damit der Client aktualisieren kann.

Führen Sie ihn in einem vertrauenswürdigen Netzwerk oder an Loopback gebunden aus. Für eine Multi-Tenant- oder öffentliche Bereitstellung stellen Sie ein eigenes Gateway/Auth davor.

Releases

Ein Release zu erstellen ist bewusst: Erhöhen Sie die Version in package.json, führen Sie npm run sync-version aus (aktualisiert manifest.json, server.json und .cursor-plugin/plugin.json), und pushen Sie dann ein passendes v*-Tag:

git tag v2.0.0
git push origin v2.0.0

Dieser getaggte Commit (mit Skills, die zum Schnittzeitpunkt eingefroren sind) veröffentlicht:

• @growthbook/mcp auf npm — Vorabversionen (Versionen mit -, z. B. 2.0.0-beta.1) gehen unter den beta-Dist-Tag; stabile Versionen werden latest
• ein Multi-Arch-Image (amd64 + arm64) nach ghcr.io/growthbook/growthbook-mcp (:<version>, plus :<major>, :<major>.<minor> und :latest für stabile Releases)
• einen Eintrag im MCP-Registry
• ein GitHub-Release

Das Cursor-Plugin wird nicht von CI veröffentlicht: Cursor überprüft das Plugin erneut vom Standard-Branch, nachdem die Versionserhöhung eingegangen ist.

Installieren Sie ein Release mit npx @growthbook/mcp@<version> oder ziehen Sie ghcr.io/growthbook/growthbook-mcp:<version>.