mcp-graphql-bridge
mcp-graphql-bridge
Ein generischer MCP-Server (Model Context Protocol), der jede GraphQL-API mit Claude Code verbindet. Er untersucht Ihr GraphQL-Schema und stellt jede Query und Mutation als einzelnes Tool bereit, sodass Claude direkt mit Ihrer API interagieren kann.
Funktionsweise
Beim Start führt der Server folgende Schritte aus:
Er sucht nach einer
schema-introspection.json-Datei im Arbeitsverzeichnis (schnell, kein Netzwerkaufruf)Falls nicht gefunden, führt er eine Live-Introspektion gegen die
GRAPHQL_INTROSPECTION_URLdurchEr registriert ein Tool pro Query (
query__<name>) und eines pro Mutation (mutation__<name>)Er registriert immer ein generisches
execute_graphql-Fallback-Tool und einget_type_details-Explorer-Tool
Related MCP server: GraphQL MCP Server
Anforderungen
Node.js >= 18
Einrichtung
Schritt 1: Installation
Option A: Installation über npm (empfohlen)
npm install -g mcp-graphql-bridgeOption B: Klonen und Build aus dem Quellcode
git clone https://github.com/murilopereira/mcp-graphql-bridge.git
cd mcp-graphql-bridge
npm install
npm run buildSchritt 2: Umgebungsvariablen konfigurieren
Variable | Erforderlich | Beschreibung |
| Ja | Endpunkt für Queries und Mutationen |
| Ja | Endpunkt für die Schema-Introspektion (kann derselbe wie oben sein) |
| Ja | Bearer-Token für die Authentifizierung |
Sie können diese in einer .env-Datei im Projektstammverzeichnis festlegen:
GRAPHQL_API_URL=https://your-api.example.com/graphql
GRAPHQL_INTROSPECTION_URL=https://your-api.example.com/graphql
GRAPHQL_TOKEN=your-bearer-tokenOder übergeben Sie sie direkt über den Befehl claude mcp add (siehe unten).
Schritt 3: (Optional) Schema-Snapshot vorab generieren
Standardmäßig untersucht der Server Ihr Schema live beim Start – es ist keine Datei erforderlich. Verwenden Sie diesen Schritt nur, wenn Ihre API die Introspektion in der Produktion deaktiviert hat oder Sie schnellere Startzeiten wünschen:
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.jsonZu Claude Code hinzufügen
Option A: Benutzerbereich (nur für Sie)
Bei Installation über 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-bridgeBei Klonen aus dem Quellcode:
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.jsWichtig: Stellen Sie sicher, dass Sie
mcp-graphql-bridge/dist/index.js(die kompilierte Ausgabe) verwenden, nichtmcp-graphql-bridge/index.js. Der TypeScript-Quellcode muss zuerst mitnpm run builderstellt werden, und der Einstiegspunkt befindet sich imdist/-Ordner.
Option B: Projektbereich (für Ihr Team freigegeben über .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-bridgeHinweis: Verwenden Sie absolute Pfade. Alle
--env- und--transport-Flags müssen vor dem Servernamen stehen.
Verbindung überprüfen
claude mcp listFühren Sie dann in einer Claude Code-Sitzung /mcp aus, um die verfügbaren Server und Tools anzuzeigen.
Verfügbare Tools
Tool | Beschreibung |
| Ein Tool pro GraphQL-Query-Feld |
| Ein Tool pro GraphQL-Mutationsfeld |
| Generisches Fallback – führt jede Query oder Mutation aus |
| Felder eines bestimmten GraphQL-Typs erkunden |
Alle pro-Operation-Tools akzeptieren ein spezielles __fields-Argument, in dem Sie ein benutzerdefiniertes GraphQL-Auswahlset angeben können (z. B. { id name status }). Wenn es weggelassen wird, werden nur skalare Felder zurückgegeben.
Docker
Image erstellen
docker build -t mcp-graphql-bridge .Zu Claude Code über Docker hinzufügen
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-bridgeHinweis: Das
-i-Flag (ohne-t) ist erforderlich – es hält stdin für das MCP-stdio-Protokoll offen.
Entwicklung
npm run dev # watch mode: rebuilds and restarts on file changes
npm run build # one-off TypeScript compile
npm start # run the compiled serverFehlerbehebung
Fehler: Cannot find module '.../index.js'
Wenn Sie eine Fehlermeldung wie diese sehen:
Error: Cannot find module '/path/to/mcp-graphql-bridge/index.js'Sie verweisen auf die falsche Datei. Der TypeScript-Quellcode muss zuerst kompiliert werden, und der Einstiegspunkt befindet sich im dist/-Ordner:
Korrekter Pfad: /path/to/mcp-graphql-bridge/dist/index.js
Falscher Pfad: /path/to/mcp-graphql-bridge/index.js
Lösung:
Stellen Sie sicher, dass Sie
npm run buildausgeführt haben (erstellt dendist/-Ordner)Aktualisieren Sie Ihre MCP-Konfiguration, um den vollständigen Pfad mit Endung
/dist/index.jszu verwenden
Schema-Introspektion schlägt fehl
Wenn der Server startet, aber "Schema introspection failed" anzeigt, hat Ihre GraphQL-API möglicherweise die Introspektion in der Produktion deaktiviert. Verwenden Sie den curl-Befehl in Schritt 3 der Einrichtung, um eine schema-introspection.json-Datei vorab zu generieren.
Tools erscheinen nicht in Claude Code
Führen Sie
claude mcp listaus, um zu überprüfen, ob der Server registriert istFühren Sie
/mcpin einer Claude Code-Sitzung aus, um die verfügbaren Tools anzuzeigenÜberprüfen Sie, ob alle erforderlichen Umgebungsvariablen gesetzt sind (
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