mcp-graphql-bridge

Un servidor MCP (Model Context Protocol) genérico que conecta cualquier API GraphQL con Claude Code. Realiza una introspección de tu esquema GraphQL y expone cada consulta y mutación como una herramienta individual, permitiendo que Claude interactúe directamente con tu API.

Cómo funciona

Al iniciarse, el servidor:

1. Busca un archivo schema-introspection.json en el directorio de trabajo (rápido, sin llamadas de red)

2. Si no lo encuentra, ejecuta una introspección en tiempo real contra GRAPHQL_INTROSPECTION_URL

3. Registra una herramienta por consulta (query__<name>) y una por mutación (mutation__<name>)

4. Registra siempre una herramienta de respaldo genérica execute_graphql y una herramienta de exploración get_type_details

Requisitos

• Node.js >= 18

Configuración

Paso 1: Instalación

Opción A: Instalar desde npm (recomendado)

npm install -g mcp-graphql-bridge

Opción B: Clonar y compilar desde el código fuente

git clone https://github.com/murilopereira/mcp-graphql-bridge.git
cd mcp-graphql-bridge
npm install
npm run build

Paso 2: Configurar variables de entorno

Puedes configurarlas en un archivo .env en la raíz del proyecto:

GRAPHQL_API_URL=https://your-api.example.com/graphql
GRAPHQL_INTROSPECTION_URL=https://your-api.example.com/graphql
GRAPHQL_TOKEN=your-bearer-token

O pasarlas directamente mediante el comando claude mcp add (ver más abajo).

Paso 3: (Opcional) Pre-generar instantánea del esquema

Por defecto, el servidor realiza la introspección de tu esquema en tiempo real al iniciarse; no se necesita ningún archivo. Utiliza este paso solo si tu API tiene la introspección deshabilitada en producción, o si deseas tiempos de inicio más rápidos:

curl -s -X POST https://your-api.example.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-bearer-token" \
  -d '{"query":"{ __schema { queryType { fields { name description args { name description defaultValue type { kind name ofType { kind name ofType { kind name ofType { kind name } } } } } type { kind name ofType { kind name ofType { kind name } } } } } mutationType { fields { name description args { name description defaultValue type { kind name ofType { kind name ofType { kind name ofType { kind name } } } } } type { kind name ofType { kind name ofType { kind name } } } } } } }"}' \
  > schema-introspection.json

Añadir a Claude Code

Opción A: Ámbito de usuario (solo para ti)

Si se instaló desde npm:

claude mcp add --transport stdio \
  --env GRAPHQL_API_URL=https://your-api.example.com/graphql \
  --env GRAPHQL_INTROSPECTION_URL=https://your-api.example.com/graphql \
  --env GRAPHQL_TOKEN=your-bearer-token \
  graphql-bridge -- mcp-graphql-bridge

Si se clonó desde el código fuente:

claude mcp add --transport stdio \
  --env GRAPHQL_API_URL=https://your-api.example.com/graphql \
  --env GRAPHQL_INTROSPECTION_URL=https://your-api.example.com/graphql \
  --env GRAPHQL_TOKEN=your-bearer-token \
  graphql-bridge -- node /absolute/path/to/mcp-graphql-bridge/dist/index.js

Importante: Asegúrate de usar mcp-graphql-bridge/dist/index.js (la salida compilada), no mcp-graphql-bridge/index.js. El código fuente en TypeScript debe compilarse primero con npm run build, y el punto de entrada se encuentra en la carpeta dist/.

Opción B: Ámbito de proyecto (compartido con tu equipo mediante .mcp.json)

claude mcp add --transport stdio --scope project \
  --env GRAPHQL_API_URL=https://your-api.example.com/graphql \
  --env GRAPHQL_INTROSPECTION_URL=https://your-api.example.com/graphql \
  --env GRAPHQL_TOKEN=your-bearer-token \
  graphql-bridge -- mcp-graphql-bridge

Nota: Usa rutas absolutas. Todas las banderas --env y --transport deben ir antes del nombre del servidor.

Verificar la conexión

claude mcp list

Luego, en una sesión de Claude Code, ejecuta /mcp para ver los servidores y herramientas disponibles.

Herramientas disponibles

Todas las herramientas por operación aceptan un argumento especial __fields donde puedes proporcionar un conjunto de selección GraphQL personalizado (p. ej., { id name status }). Si se omite, solo se devuelven los campos escalares.

Docker

Construir la imagen

docker build -t mcp-graphql-bridge .

Añadir a Claude Code mediante Docker

claude mcp add --transport stdio \
  --env GRAPHQL_API_URL=https://your-api.example.com/graphql \
  --env GRAPHQL_INTROSPECTION_URL=https://your-api.example.com/graphql \
  --env GRAPHQL_TOKEN=your-bearer-token \
  graphql-bridge -- docker run -i --rm \
  -e GRAPHQL_API_URL -e GRAPHQL_INTROSPECTION_URL -e GRAPHQL_TOKEN \
  mcp-graphql-bridge

Nota: La bandera -i (sin -t) es necesaria; mantiene stdin abierto para el protocolo stdio de MCP.

Desarrollo

npm run dev   # watch mode: rebuilds and restarts on file changes
npm run build # one-off TypeScript compile
npm start     # run the compiled server

Solución de problemas

Error: Cannot find module '.../index.js'

Si ves un error como:

Error: Cannot find module '/path/to/mcp-graphql-bridge/index.js'

Estás apuntando al archivo incorrecto. El código fuente en TypeScript debe compilarse primero, y el punto de entrada se encuentra en la carpeta dist/:

Ruta correcta: /path/to/mcp-graphql-bridge/dist/index.js Ruta incorrecta: /path/to/mcp-graphql-bridge/index.js

Solución:

1. Asegúrate de haber ejecutado npm run build (crea la carpeta dist/)

2. Actualiza tu configuración de MCP para usar la ruta completa que termina en /dist/index.js

La introspección del esquema falla

Si el servidor se inicia pero muestra "Schema introspection failed", es posible que tu API GraphQL tenga la introspección deshabilitada en producción. Usa el comando curl en el paso 3 de la Configuración para pre-generar un archivo schema-introspection.json.

Las herramientas no aparecen en Claude Code

1. Ejecuta claude mcp list para verificar que el servidor esté registrado

2. Ejecuta /mcp en una sesión de Claude Code para ver las herramientas disponibles

3. Comprueba que todas las variables de entorno requeridas estén configuradas (GRAPHQL_API_URL, GRAPHQL_INTROSPECTION_URL, GRAPHQL_TOKEN)