mcp-graphql-bridge

A generic MCP (Model Context Protocol) server that bridges any GraphQL API to Claude Code. It introspects your GraphQL schema and exposes each query and mutation as an individual tool, letting Claude interact with your API directly.

How it works

On startup the server will:

1. Look for a schema-introspection.json file in the working directory (fast, no network call)
2. If not found, run live introspection against GRAPHQL_INTROSPECTION_URL
3. Register one tool per query (query__<name>) and one per mutation (mutation__<name>)
4. Always register a generic execute_graphql fallback tool and a get_type_details explorer tool

Requirements

• Node.js >= 20

Setup

Step 1: Install

Option A: Install from npm (recommended)

npm install -g mcp-graphql-bridge

Option B: Clone and build from source

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

Step 2: Configure environment variables

For schemas with hundreds of fields (GitHub's GraphQL API has 284 root fields — 32 queries, 252 mutations), GRAPHQL_MAX_TOOLS and GRAPHQL_INCLUDE_MUTATIONS are what keep registration bounded and predictable. If the cap truncates the schema, stderr logs exactly how many queries/mutations were registered vs. available.

No configuration is required to try the server — with nothing set, it starts against the public demo API above and logs that it's doing so. See docs/architecture.md for the full token model and why the GraphQL endpoint is fixed per deployment rather than a per-request parameter.

You can set these in a .env file at the project root:

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

Or pass them directly via the claude mcp add command (see below).

Step 3: (Optional) Pre-generate schema snapshot

By default the server introspects your schema live on startup — no file needed, and it automatically retries at a shallower query depth if your API rejects the full-depth attempt (some APIs, especially CDN-fronted ones, enforce a query depth limit). Use this step only if your API has introspection disabled entirely in production, or you want faster startup times:

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 ofType { kind name ofType { kind name ofType { kind name } } } } } } } } type { kind name ofType { kind name ofType { kind name ofType { kind name ofType { 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 ofType { kind name ofType { kind name ofType { kind name } } } } } } } } type { kind name ofType { kind name ofType { kind name ofType { kind name ofType { kind name ofType { kind name ofType { kind name } } } } } } } } } } }"}' \
  > schema-introspection.json

If your API rejects this with a depth/complexity-limit error, shrink the ofType { ... } nesting (each level resolves one more NonNull/List wrapper — most real-world types need 2-3 levels; only doubly-wrapped lists like [[Int!]!]! need more).

Adding to Claude Code

Option A: User scope (just for you)

If installed from 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

If cloned from source:

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

Important: Make sure to use mcp-graphql-bridge/dist/index.js (the compiled output), not mcp-graphql-bridge/index.js. The TypeScript source must be built first with npm run build, and the entry point is in the dist/ folder.

Option B: Project scope (shared with your team via .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

Note: Use absolute paths. All --env and --transport flags must come before the server name.

Verify the connection

claude mcp list

Then in a Claude Code session, run /mcp to see available servers and tools.

Examples

Two worked walkthroughs — a small public schema with no configuration needed, then a large, real enterprise-scale schema requiring auth and tool-count limits.

Example 1: Countries API (small schema, no auth)

This is the zero-config default — nothing to install or configure beyond the server itself.

1. Add the server with no environment variables at all:

   Terminal

   Copy

   claude mcp add --transport stdio graphql-countries -- mcp-graphql-bridge
   

2. Restart Claude Code (or run /mcp to confirm graphql-countries is connected). You should see tools like query__country, query__countries, and query__continents.

3. Ask Claude:

   Using graphql-countries, find the country with code "BR", then list its continent's other countries.

   Claude calls query__country({ code: "BR", __fields: "{ name continent { code name } }" }), then query__continent or query__countries({ __fields: "{ name }" }) filtered by the result.

4. Try an invalid code to see error passthrough:

   Look up the country with code "ZZZ".

   Returns the GraphQL API's own error text — the bridge passes it through rather than masking it.

Example 2: GitHub GraphQL API (large schema, auth + tool limits)

GitHub's GraphQL API has 284 root fields (32 queries, 252 mutations) — far more than the GRAPHQL_MAX_TOOLS default of 128, and it needs a token for every request, including introspection (unlike GitHub's REST API, which allows some anonymous reads).

1. Add the server, scoped to read-only access:

   server.ts

   Copy

   export GH_TOKEN=ghp_your_personal_access_token  # or: source a gitignored .env file first
   
   claude mcp add --transport stdio graphql-github \
     --env GRAPHQL_API_URL=https://api.github.com/graphql \
     --env GRAPHQL_INTROSPECTION_URL=https://api.github.com/graphql \
     --env GRAPHQL_TOKEN=$GH_TOKEN \
     --env GRAPHQL_INCLUDE_MUTATIONS=false \
     graphql-bridge -- mcp-graphql-bridge
   

   GRAPHQL_INCLUDE_MUTATIONS=false registers all 32 (read-only) queries and zero mutations — comfortably under the cap, and a meaningfully safer default for an AI agent than exposing all 252 write operations.

2. Ask Claude:

   Using graphql-github, look up the repository facebook/react and tell me its star count.

   Claude calls query__repository({ owner: "facebook", name: "react", __fields: "{ name stargazerCount }" }).

3. To also reach mutations, drop GRAPHQL_INCLUDE_MUTATIONS=false and raise the cap (GRAPHQL_MAX_TOOLS=400), understanding that this exposes write access to your GitHub account scoped to whatever permissions your token has.

Available tools