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:

1. Er sucht nach einer schema-introspection.json-Datei im Arbeitsverzeichnis (schnell, kein Netzwerkaufruf)

2. Falls nicht gefunden, führt er eine Live-Introspektion gegen die GRAPHQL_INTROSPECTION_URL durch

3. Er registriert ein Tool pro Query (query__<name>) und eines pro Mutation (mutation__<name>)

4. Er registriert immer ein generisches execute_graphql-Fallback-Tool und ein get_type_details-Explorer-Tool

Anforderungen

• Node.js >= 18

Einrichtung

Schritt 1: Installation

Option A: Installation über npm (empfohlen)

npm install -g mcp-graphql-bridge

Option 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 build

Schritt 2: Umgebungsvariablen konfigurieren

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-token

Oder ü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.json

Zu 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-bridge

Bei 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.js

Wichtig: Stellen Sie sicher, dass Sie mcp-graphql-bridge/dist/index.js (die kompilierte Ausgabe) verwenden, nicht mcp-graphql-bridge/index.js. Der TypeScript-Quellcode muss zuerst mit npm run build erstellt werden, und der Einstiegspunkt befindet sich im dist/-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-bridge

Hinweis: Verwenden Sie absolute Pfade. Alle --env- und --transport-Flags müssen vor dem Servernamen stehen.

Verbindung überprüfen

claude mcp list

Führen Sie dann in einer Claude Code-Sitzung /mcp aus, um die verfügbaren Server und Tools anzuzeigen.

Verfügbare Tools

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-bridge

Hinweis: 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 server

Fehlerbehebung

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:

1. Stellen Sie sicher, dass Sie npm run build ausgeführt haben (erstellt den dist/-Ordner)

2. Aktualisieren Sie Ihre MCP-Konfiguration, um den vollständigen Pfad mit Endung /dist/index.js zu 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

1. Führen Sie claude mcp list aus, um zu überprüfen, ob der Server registriert ist

2. Führen Sie /mcp in einer Claude Code-Sitzung aus, um die verfügbaren Tools anzuzeigen

3. Überprüfen Sie, ob alle erforderlichen Umgebungsvariablen gesetzt sind (GRAPHQL_API_URL, GRAPHQL_INTROSPECTION_URL, GRAPHQL_TOKEN)