GrowthBook

GrowthBook MCP Thin

Un servidor MCP ligero para GrowthBook con cuatro herramientas:

Herramienta	Propósito
growthbook_list_skills	Lista las habilidades del agente de GrowthBook empaquetadas (nombre + descripción)
growthbook_read_skill	Devuelve el markdown completo de la habilidad (flujo de trabajo + barreras de protección)
growthbook_api_read	Pase autenticado GET a la API de GrowthBook
growthbook_api_write	Pase autenticado POST/PUT/PATCH/DELETE

La competencia reside en el repositorio de habilidades y se empaqueta en tiempo de compilación. La capacidad se divide en herramientas de API de lectura y escritura (sin formateadores por endpoint) para que los clientes puedan honrar correctamente readOnlyHint / destructiveHint.

Las herramientas tienen el prefijo growthbook_ para que no sean ambiguas cuando un cliente tiene varios servidores MCP cargados.

Instalar / ejecutar

npm install
npm run build

Apunte su cliente MCP al punto de entrada compilado:

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

O ejecute el paquete publicado:

npx @growthbook/mcp

Variables de entorno

Variable	Requerida	Predeterminada	Propósito
GB_API_KEY	Sí para stdio; opcional para HTTP OAuth	—	Clave API de GrowthBook o token de acceso personal
GB_API_URL	No	https://api.growthbook.io	URL base de la API (autoalojada) y emisor AS de OAuth predeterminado
GB_MCP_TRANSPORT	No	stdio	stdio o http
GB_MCP_PORT	No	3333	Puerto de escucha HTTP (cuando transport=http)
GB_MCP_HOST	No	127.0.0.1	Host de enlace HTTP
GB_MCP_URL	Sí para HTTP	—	URL base pública de MCP incluida en los metadatos del recurso OAuth (el servidor se niega a iniciar en modo HTTP sin ella)
GB_OAUTH_ISSUER	No	GB_API_URL	URL del emisor AS de OAuth de GrowthBook
GB_HTTP_HEADER_*	No	—	Encabezados de solicitud adicionales (p. ej., GB_HTTP_HEADER_CF_ACCESS_TOKEN)
GB_SKILLS_ENABLED	No	true	Establecer en false / 0 para deshabilitar las herramientas de habilidades

Modo 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

Los clientes se conectan a:

• http://127.0.0.1:3333/mcp — completo (habilidades + lectura/escritura de API)
• http://127.0.0.1:3333/mcp/api — solo capacidad (growthbook_api_read + growthbook_api_write)

Las solicitudes no autenticadas reciben 401 con WWW-Authenticate apuntando a /.well-known/oauth-protected-resource, que anuncia el Servidor de Autorización de GrowthBook.

Antes de manejar MCP, el servidor sondea REST de GrowthBook (GET /api/v1/) con el bearer. Un 401 de esa sonda (o posteriormente de una herramienta de API) produce HTTP 401 con error="invalid_token" para que el cliente MCP pueda actualizar, en lugar de mostrar "This API key has expired" como un error de herramienta. Un 403 se trata como un bearer aceptado (permiso denegado ≠ token no válido) para que los clientes no se vean forzados a un bucle de actualización.

Modo solo capacidad

HTTP (recomendado para remoto): apunte el cliente a /mcp/api en lugar de /mcp:

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

Ruta	Herramientas
/mcp	growthbook_list_skills, growthbook_read_skill, growthbook_api_read, growthbook_api_write (a menos que GB_SKILLS_ENABLED=false)
/mcp/api	growthbook_api_read, growthbook_api_write solamente

stdio / para todo el proceso: establezca env para que las habilidades nunca se registren:

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

Cuando las habilidades están deshabilitadas, solo se registran las herramientas de lectura/escritura de API. growthbook_list_skills y growthbook_read_skill no se exponen.

Cómo se empaquetan las habilidades

npm run build   # tsc && bundle-skills

scripts/bundle-skills.mjs copia cada skills/*/SKILL.md del checkout canónico de habilidades en server/skills/<name>.md.

Resolución de la ruta de origen:

1. Variable de entorno SKILLS_SRC (ruta a la raíz del repositorio de habilidades), o
2. ../skills (directorio hermano)

El repositorio de habilidades sigue siendo la fuente de verdad — este paquete nunca bifurca el contenido de las habilidades.

Uso de habilidades con las herramientas de API

Las habilidades empaquetadas aún muestran flujos de trabajo como:

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

Este servidor MCP no ejecuta un shell a gb-call. Mapee GET → growthbook_api_read y POST/PUT/PATCH/DELETE → growthbook_api_write con la misma ruta y cadena de cuerpo JSON opcional. Las instrucciones del servidor y la salida de growthbook_read_skill incluyen esta nota de puente.

Detalle de herramientas

growthbook_api_read / growthbook_api_write

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

• Lectura: solo GET (readOnlyHint: true)
• Escritura: POST | PUT | PATCH | DELETE (destructiveHint: true)
• Devuelve el cuerpo de respuesta sin procesar en 2xx
• En caso de no 2xx, devuelve un error procesable (isError: true) que cubre fallos de autenticación, sugerencias de 404 autoalojadas y límites de velocidad
• Las rutas de forma libre apuntan a la API REST de GrowthBook

growthbook_list_skills / growthbook_read_skill

Solo se registran cuando GB_SKILLS_ENABLED no está deshabilitado. growthbook_read_skill devuelve el contenido completo de SKILL.md para que el agente pueda seguir los pasos del flujo de trabajo y las barreras de protección.

Desarrollo

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

Modo HTTP independiente

Por defecto, el servidor se ejecuta sobre stdio. Establezca GB_MCP_TRANSPORT=http para ejecutarlo como un servidor HTTP independiente que expone MCP en /mcp (habilidades + herramientas de API) y /mcp/api (solo capacidad), detrás de una superficie de recurso protegido OAuth 2.0 (metadatos RFC 9728 + RFC 6750 WWW-Authenticate).

• GB_MCP_URL (requerida en modo HTTP) — la URL base pública del servidor. Se incluye en el recurso OAuth (audiencia) y los metadatos del recurso protegido, por lo que nunca se deriva de los encabezados de solicitud. El servidor se niega a iniciar sin ella.
• GB_MCP_PORT (predeterminado 3333) y GB_MCP_HOST (predeterminado 127.0.0.1).
• Los bearers entrantes se validan sondeando la API REST de GrowthBook; un token rechazado obtiene HTTP 401 + WWW-Authenticate para que el cliente pueda actualizar.

Ejecútelo en una red de confianza o vinculado a loopback. Para una implementación multiinquilino o pública, coloque su propia puerta de enlace/autenticación al frente.

Lanzamientos

Hacer un lanzamiento es deliberado: aumente la versión en package.json, luego empuje una etiqueta v* coincidente:

git tag v2.0.0
git push origin v2.0.0

Ese commit etiquetado (con las habilidades congeladas en el momento del corte) publica:

• @growthbook/mcp a npm — las versiones preliminares (versiones con un -, p. ej., 2.0.0-beta.1) van bajo la etiqueta de distribución beta; las versiones estables se convierten en latest
• una imagen multiarquitectura (amd64 + arm64) en ghcr.io/growthbook/growthbook-mcp (:<version>, más :<major>, :<major>.<minor> y :latest para lanzamientos estables)
• una entrada en el registro de MCP
• un Lanzamiento de GitHub

Instale un lanzamiento con npx @growthbook/mcp@<version> o extraiga ghcr.io/growthbook/growthbook-mcp:<version>.