Skip to main content
Glama
mcp-graphql-bridge

mcp-graphql-bridge

mcp-graphql-bridge

npm version CI License: MIT Node.js >= 18

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

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

Variable

Erforderlich

Beschreibung

GRAPHQL_API_URL

Ja

Endpunkt für Queries und Mutationen

GRAPHQL_INTROSPECTION_URL

Ja

Endpunkt für die Schema-Introspektion (kann derselbe wie oben sein)

GRAPHQL_TOKEN

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

Tool

Beschreibung

query__<name>

Ein Tool pro GraphQL-Query-Feld

mutation__<name>

Ein Tool pro GraphQL-Mutationsfeld

execute_graphql

Generisches Fallback – führt jede Query oder Mutation aus

get_type_details

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

Available Tools

2 tools
execute_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

    A3.9/5.0

    Scored across 2 tools

    Disambiguation5/5

    The two tools serve clearly distinct purposes: executing GraphQL operations vs. retrieving type metadata. No overlap in functionality.

    Naming Consistency5/5

    Both tool names follow a consistent verb_noun pattern using snake_case (execute_graphql, get_type_details), making the intent clear and predictable.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A 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 context
      46
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol server that enables LLMs to interact with GraphQL APIs by providing schema introspection and query execution capabilities.
      3
      MIT