mcp-graphql-bridge
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:
Busca un archivo
schema-introspection.jsonen el directorio de trabajo (rápido, sin llamadas de red)Si no lo encuentra, ejecuta una introspección en tiempo real contra
GRAPHQL_INTROSPECTION_URLRegistra una herramienta por consulta (
query__<name>) y una por mutación (mutation__<name>)Registra siempre una herramienta de respaldo genérica
execute_graphqly una herramienta de exploraciónget_type_details
Related MCP server: GraphQL MCP Server
Requisitos
Node.js >= 18
Configuración
Paso 1: Instalación
Opción A: Instalar desde npm (recomendado)
npm install -g mcp-graphql-bridgeOpció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 buildPaso 2: Configurar variables de entorno
Variable | Requerida | Descripción |
| Sí | Endpoint utilizado para consultas y mutaciones |
| Sí | Endpoint utilizado para la introspección del esquema (puede ser el mismo que el anterior) |
| Sí | Token Bearer para autenticación |
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-tokenO 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.jsonAñ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-bridgeSi 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.jsImportante: Asegúrate de usar
mcp-graphql-bridge/dist/index.js(la salida compilada), nomcp-graphql-bridge/index.js. El código fuente en TypeScript debe compilarse primero connpm run build, y el punto de entrada se encuentra en la carpetadist/.
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-bridgeNota: Usa rutas absolutas. Todas las banderas
--envy--transportdeben ir antes del nombre del servidor.
Verificar la conexión
claude mcp listLuego, en una sesión de Claude Code, ejecuta /mcp para ver los servidores y herramientas disponibles.
Herramientas disponibles
Herramienta | Descripción |
| Una herramienta por campo de consulta GraphQL |
| Una herramienta por campo de mutación GraphQL |
| Respaldo genérico: ejecuta cualquier consulta o mutación |
| Explora los campos de un tipo GraphQL específico |
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-bridgeNota: 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 serverSolució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:
Asegúrate de haber ejecutado
npm run build(crea la carpetadist/)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
Ejecuta
claude mcp listpara verificar que el servidor esté registradoEjecuta
/mcpen una sesión de Claude Code para ver las herramientas disponiblesComprueba que todas las variables de entorno requeridas estén configuradas (
GRAPHQL_API_URL,GRAPHQL_INTROSPECTION_URL,GRAPHQL_TOKEN)
Available Tools
2 toolsexecute_graphqlA
Execute any GraphQL query or mutation against the API. Use this when no specific tool exists for your operation.
Inputs: query (required), variables, bearer_token, custom_headers.
get_type_detailsB
Get fields of a specific GraphQL type to know what to put in __fields
Inputs: typeName (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
The two tools serve clearly distinct purposes: executing GraphQL operations vs. retrieving type metadata. No overlap in functionality.
Both tool names follow a consistent verb_noun pattern using snake_case (execute_graphql, get_type_details), making the intent clear and predictable.
For a GraphQL bridge, two tools is minimal but still covers the essential operations of executing queries and exploring types. Slightly under-scoped but reasonable.
The tool surface covers core GraphQL operations (any query/mutation) and type introspection. Minor gaps exist (e.g., no dedicated tool for listing mutations), but the generic execute tool and type details suffice for agents familiar with GraphQL.
Maintenance
Related MCP Connectors
The Grafbase MCP server sits in front of a GraphQL API and exposes an MCP protocol-compliant interface that allows AI agents and LLMs to explore and query GraphQL APIs using natural language. It provides tools to search schemas, introspect types and fields, and execute GraphQL queries while minimizing context bloat by returning only relevant schema subsets, with built-in support for authentication, authorization, and configurable access control.
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA MCP server that exposes GraphQL schema information to LLMs like Claude. This server allows an LLM to explore and understand large GraphQL schemas through a set of specialized tools, without needing to load the whole schema into the context46MIT
- AlicenseCqualityDmaintenanceA TypeScript server that provides Claude AI with seamless access to any GraphQL API through the Model Context Protocol.616 npm12MIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that enables LLMs to interact with GraphQL APIs by providing schema introspection and query execution capabilities.3MIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that enables LLMs to interact with GraphQL APIs by providing schema introspection and query execution capabilities.MIT