GrowthBook

GrowthBook MCP Thin

Un serveur MCP léger pour GrowthBook avec quatre outils :

Outil	Objectif
growthbook_list_skills	Lister les compétences agent GrowthBook incluses (nom + description)
growthbook_read_skill	Renvoyer le markdown complet de la compétence (workflow + garde-fous)
growthbook_api_read	Passage direct authentifié GET vers l'API GrowthBook
growthbook_api_write	Passage direct authentifié POST/PUT/PATCH/DELETE

Les compétences vivent dans le dépôt skills et sont embarquées au moment de la compilation. Les capacités sont divisées en outils API de lecture et d'écriture (sans formatteurs par endpoint) afin que les clients puissent respecter correctement readOnlyHint / destructiveHint.

Les outils sont préfixés avec growthbook_ afin qu'ils restent sans ambiguïté lorsqu'un client a plusieurs serveurs MCP chargés.

Installation / exécution

npm install
npm run build

Pointez votre client MCP vers le point d'entrée compilé :

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

Ou exécutez le package publié :

npx @growthbook/mcp

Variables d'environnement

Variable	Requis	Défaut	Objectif
GB_API_KEY	Oui pour stdio ; optionnel pour HTTP OAuth	—	Clé API GrowthBook ou jeton d'accès personnel
GB_API_URL	Non	https://api.growthbook.io	URL de base API (auto-hébergé) et émetteur AS OAuth par défaut
GB_MCP_TRANSPORT	Non	stdio	stdio ou http
GB_MCP_PORT	Non	3333	Port d'écoute HTTP (lorsque transport=http)
GB_MCP_HOST	Non	127.0.0.1	Hôte de liaison HTTP
GB_MCP_URL	Oui pour HTTP	—	URL de base MCP publique intégrée dans les métadonnées de ressource OAuth (le serveur refuse de démarrer en mode HTTP sans elle)
GB_OAUTH_ISSUER	Non	GB_API_URL	URL de l'émetteur AS OAuth GrowthBook
GB_HTTP_HEADER_*	Non	—	En-têtes de requête supplémentaires (par ex. GB_HTTP_HEADER_CF_ACCESS_TOKEN)
GB_SKILLS_ENABLED	Non	true	Définir sur false / 0 pour désactiver les outils de compétences

Mode 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

Les clients se connectent à :

• http://127.0.0.1:3333/mcp — complet (compétences + lecture/écriture API)
• http://127.0.0.1:3333/mcp/api — capacité uniquement (growthbook_api_read + growthbook_api_write)

Les requêtes non authentifiées reçoivent 401 avec WWW-Authenticate pointant vers /.well-known/oauth-protected-resource, qui annonce le serveur d'autorisation GrowthBook.

Avant de traiter MCP, le serveur sonde l'API REST GrowthBook (GET /api/v1/) avec le jeton. Un 401 de cette sonde (ou plus tard d'un outil API) produit HTTP 401 avec error="invalid_token" afin que le client MCP puisse se rafraîchir — au lieu de remonter "This API key has expired" comme erreur d'outil. Un 403 est traité comme un jeton accepté (autorisation refusée ≠ jeton invalide) afin que les clients ne soient pas contraints à une boucle de rafraîchissement.

Mode capacité uniquement

HTTP (recommandé pour le distant) : pointez le client vers /mcp/api au lieu de /mcp :

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

Chemin	Outils
/mcp	growthbook_list_skills, growthbook_read_skill, growthbook_api_read, growthbook_api_write (sauf si GB_SKILLS_ENABLED=false)
/mcp/api	growthbook_api_read, growthbook_api_write uniquement

stdio / à l'échelle du processus : définissez l'environnement pour que les compétences ne soient jamais enregistrées :

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

Lorsque les compétences sont désactivées, seuls les outils de lecture/écriture API sont enregistrés. growthbook_list_skills et growthbook_read_skill ne sont pas exposés.

Comment les compétences sont embarquées

npm run build   # tsc && bundle-skills

scripts/bundle-skills.mjs copie chaque skills/*/SKILL.md du répertoire canonique des compétences dans server/skills/<name>.md.

Résolution du chemin source :

1. SKILLS_SRC variable d'environnement (chemin vers la racine du dépôt de compétences), ou
2. ../skills (répertoire adjacent)

Le dépôt de compétences reste la source de vérité — ce package ne fork jamais le contenu des compétences.

Utiliser les compétences avec les outils API

Les compétences embarquées affichent toujours les workflows comme :

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

Ce serveur MCP ne fait pas appel à gb-call. Faites correspondre GET → growthbook_api_read et POST/PUT/PATCH/DELETE → growthbook_api_write avec le même chemin et une chaîne de corps JSON optionnelle. Les instructions du serveur et la sortie growthbook_read_skill incluent cette note de pont.

Détail des outils

growthbook_api_read / growthbook_api_write

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

• Lecture : GET uniquement (readOnlyHint: true)
• Écriture : POST | PUT | PATCH | DELETE (destructiveHint: true)
• Renvoie le corps de réponse brut sur 2xx
• Sur non-2xx, renvoie une erreur exploitable (isError: true) couvrant les échecs d'authentification, les indices de 404 auto-hébergé et les limites de débit
• Les chemins libres ciblent l'API REST GrowthBook

growthbook_list_skills / growthbook_read_skill

Enregistrés uniquement lorsque GB_SKILLS_ENABLED n'est pas désactivé. growthbook_read_skill renvoie le contenu complet de SKILL.md afin que l'agent puisse suivre les étapes du workflow et les garde-fous.

Développement

# Requires a sibling checkout at ../skills (or SKILLS_SRC)
npm install
npm run build
npm start

Mode HTTP autonome

Par défaut, le serveur fonctionne via stdio. Définissez GB_MCP_TRANSPORT=http pour l'exécuter comme serveur HTTP autonome qui expose MCP sur /mcp (compétences + outils API) et /mcp/api (capacité uniquement), derrière une surface de ressource protégée OAuth 2.0 (métadonnées RFC 9728 + RFC 6750 WWW-Authenticate).

• GB_MCP_URL (requis en mode HTTP) — l'URL de base publique du serveur. Elle est intégrée dans la ressource OAuth (audience) et les métadonnées de ressource protégée, donc elle n'est jamais dérivée des en-têtes de requête. Le serveur refuse de démarrer sans elle.
• GB_MCP_PORT (défaut 3333) et GB_MCP_HOST (défaut 127.0.0.1).
• Les jetons d'accès entrants sont validés en sondant l'API REST GrowthBook ; un jeton rejeté reçoit HTTP 401 + WWW-Authenticate afin que le client puisse se rafraîchir.

Exécutez-le sur un réseau de confiance ou lié à loopback. Pour un déploiement multi-tenant ou public, placez-le derrière votre propre passerelle/auth.

Versions

Publier une version est délibéré : augmentez la version dans package.json, puis poussez un tag v* correspondant :

git tag v2.0.0
git push origin v2.0.0

Ce commit taggé (avec les compétences figées au moment de la publication) publie :

• @growthbook/mcp sur npm — les préversions (versions avec un -, par exemple 2.0.0-beta.1) vont sous le dist-tag beta ; les versions stables deviennent latest
• une image multi-arch (amd64 + arm64) vers ghcr.io/growthbook/growthbook-mcp (:<version>, plus :<major>, :<major>.<minor>, et :latest pour les versions stables)
• une entrée dans le registre MCP
• une version GitHub

Installez une version avec npx @growthbook/mcp@<version> ou tirez ghcr.io/growthbook/growthbook-mcp:<version>.