GrowthBook

GrowthBook MCP Thin

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

Tool	Zweck
growthbook_list_skills	Listet Einstiegspunkte der Top-Level-Skills auf (Name + Beschreibung)
growthbook_read_skill	Gibt einen gelisteten Skill oder einen qualifizierten Child-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 Fähigkeiten sind in Lese- vs. Schreib-API-Tools aufgeteilt (keine Per-Endpoint-Formatierer), damit 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.

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 (Self-Hosted) 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-Ressourcen-Metadaten eingestempelt wird (der Server weigert sich, im HTTP-Modus ohne sie zu starten)
GB_MCP_KEEP_ALIVE_TIMEOUT_MS	Nein	90000	Idle-Keep-Alive-Timeout im HTTP-Modus. Muss das Idle-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 einem 502 fehl
GB_OAUTH_ISSUER	Nein	GB_API_URL	GrowthBook-OAuth-AS-Issuer-URL
GB_HTTP_HEADER_*	Nein	—	Zusätzliche Request-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 Fähigkeiten (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), damit Clients nicht in eine Aktualisierungsschleife gezwungen werden.

Nur-Fähigkeiten-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 Umgebungsvariable 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 Top-Level-Skill-Baum 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 vendorisieren

Es gibt keine implizite Sibling-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.

Per-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, Self-Hosted-404-Hinweise und Ratenlimits abdeckt
• Freiform-Pfade zielen auf die GrowthBook-REST-API

growthbook_list_skills / growthbook_read_skill

Nur registriert, wenn GB_SKILLS_ENABLED nicht deaktiviert ist.

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

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 Fähigkeiten) 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 und wird daher nie aus Request-Headern abgeleitet. 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 eine 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 ein Multi-Tenant- oder öffentliches Deployment setzen Sie Ihr eigenes Gateway/Auth davor.

Releases

Ein Release zu erstellen ist bewusst: Erhöhen Sie die Version in package.json und pushen Sie dann ein passendes v*-Tag:

git tag v2.0.0
git push origin v2.0.0

Dieser getaggte Commit (mit zum Zeitpunkt des Schnitts eingefrorenen Skills) veröffentlicht:

• @growthbook/mcp auf npm — Vorabversionen (Versionen mit einem -, z. B. 2.0.0-beta.1) gehen unter den beta-Dist-Tag; stabile Versionen werden zu 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

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