GrowthBook

GrowthBook MCP Thin

Un servidor MCP ligero para GrowthBook con tres herramientas:

Herramienta	Propósito
growthbook_list_skills	Listar las habilidades del agente GrowthBook incluidas (nombre + descripción)
growthbook_read_skill	Devolver el markdown completo de la habilidad (flujo de trabajo + salvaguardas)
growthbook_call_api	Paso directo REST autenticado a la API de GrowthBook

La competencia reside en el repositorio de habilidades y se incluye en el momento de la compilación. La capacidad es una herramienta growthbook_call_api genérica — sin formateadores por endpoint. La descripción de la herramienta pide a los agentes que confirmen los métodos de mutación (POST/PUT/PATCH/DELETE) con el usuario, salvo que ya se les haya indicado.

Las herramientas llevan el prefijo growthbook_ para que no haya ambigüedad cuando un cliente tiene varios servidores MCP cargados — un agente nunca debería confundir growthbook_call_api con un llamador de API genérico.

Instalación / ejecución

npm install
npm run build

Apunta tu 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 ejecuta el paquete publicado:

npx @growthbook/mcp

Variables de entorno

Variable	Obligatoria	Valor por defecto	Propósito
GB_API_KEY	Sí para stdio; opcional para OAuth HTTP	—	Clave de 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 por defecto
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	—	Cabeceras de solicitud adicionales (p. ej. GB_HTTP_HEADER_CF_ACCESS_TOKEN)
GB_SKILLS_ENABLED	No	true	Establecer a 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 + API)
• http://127.0.0.1:3333/mcp/api — solo capacidad (growthbook_call_api)

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 gestionar MCP, el servidor sondea REST de GrowthBook (GET /api/v1/) con el bearer. Un 401 de esa sonda (o posteriormente de growthbook_call_api) produce HTTP 401 con error="invalid_token" para que el cliente MCP pueda refrescar — 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 inválido) para que los clientes no se vean forzados a un bucle de refresco.

Modo solo capacidad

HTTP (recomendado para remoto): apunta 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_call_api (salvo GB_SKILLS_ENABLED=false)
/mcp/api	growthbook_call_api solamente

stdio / a nivel de proceso: establece las variables de entorno para que las habilidades nunca se registren:

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

Cuando las habilidades están deshabilitadas, solo se registra growthbook_call_api. growthbook_list_skills y growthbook_read_skill no se exponen.

Cómo se incluyen las habilidades

npm run build   # tsc && bundle-skills

scripts/bundle-skills.mjs copia cada skills/*/SKILL.md del checkout canónico de habilidades a 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 growthbook_call_api

Las habilidades incluidas siguen mostrando flujos de trabajo como:

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

Este servidor MCP no ejecuta gb-call. Cuando una habilidad muestra ese patrón, llama a la herramienta growthbook_call_api con el mismo método, ruta y cadena JSON de cuerpo opcional. Las instrucciones del servidor y la salida de growthbook_read_skill incluyen esta nota de puente.

Detalle de herramientas

growthbook_call_api

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

• Métodos: GET | POST | PUT | PATCH | DELETE
• Devuelve el cuerpo de respuesta sin procesar en 2xx
• En no-2xx, devuelve un error accionable (isError: true) que cubre fallos de autenticación, pistas de 404 autoalojado y límites de tasa
• La descripción de la herramienta + las instrucciones del servidor indican al agente que confirme POST/PUT/PATCH/DELETE con el usuario salvo que ya se le haya indicado (guía suave, no una barrera dura)

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 salvaguardas.

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. Establece GB_MCP_TRANSPORT=http para ejecutarlo como un servidor HTTP independiente que expone MCP en /mcp (habilidades + growthbook_call_api) y /mcp/api (solo capacidad), detrás de una superficie de recurso protegido OAuth 2.0 (metadatos RFC 9728 + WWW-Authenticate RFC 6750).

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

Ejecútalo en una red de confianza o vinculado a loopback. Para un despliegue multiinquilino o público, colócalo detrás de tu propia pasarela/autenticación.

Lanzamientos

Cortar un lanzamiento es deliberado: incrementa la versión en package.json, luego empuja una etiqueta v* correspondiente:

git tag v2.0.0
git push origin v2.0.0

Ese commit etiquetado (con 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) a 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

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