Graphql Bridge

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

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

Variable	Required	Description
GRAPHQL_API_URL	No	Endpoint used for queries and mutations. Defaults to a public demo API (countries.trevorblades.com) if unset — replace with your own for real use.
GRAPHQL_INTROSPECTION_URL	No	Endpoint used for schema introspection. Defaults to GRAPHQL_API_URL if unset.
GRAPHQL_TOKEN	No	Bearer token for GraphQL authentication (used for query/mutation execution). Omit for public APIs.
GRAPHQL_INTROSPECTION_TOKEN	No	Bearer token for schema introspection, if it requires different credentials than execution (e.g. a separate schema registry). Defaults to GRAPHQL_TOKEN if unset.
MCP_AUTH_TOKEN	No	Bearer token required by the hosted /mcp HTTP endpoint when MCP_TRANSPORT=http

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. Use this step only if your API has introspection disabled 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 } } } } } 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

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.

Available tools

Tool	Description
query__<name>	One tool per GraphQL query field
mutation__<name>	One tool per GraphQL mutation field
execute_graphql	Generic fallback — run any query or mutation
get_type_details	Explore fields of a specific GraphQL type

All per-operation tools accept a special __fields argument where you can provide a custom GraphQL selection set (e.g. { id name status }). If omitted, only scalar fields are returned.

Docker

Build the image

docker build -t mcp-graphql-bridge .

Add to Claude Code via 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-bridge

Note: The -i flag (no -t) is required — it keeps stdin open for the MCP stdio protocol.

HTTP deployment

For hosted MCP access, run the HTTP transport instead of stdio:

docker build -f Dockerfile.http -t mcp-graphql-bridge-http .
docker run --rm -p 8080:8080 \
  -e GRAPHQL_API_URL=https://your-api.example.com/graphql \
  -e GRAPHQL_INTROSPECTION_URL=https://your-api.example.com/graphql \
  -e GRAPHQL_TOKEN=your-bearer-token \
  mcp-graphql-bridge-http

Health checks are available at /health; MCP requests are served at /mcp.

For public-routable deployments, set MCP_AUTH_TOKEN and configure clients to send Authorization: Bearer <token> to /mcp.

See docs/deployment.md for AWS, Cloudflare, and other container hosting options.

Development

npm run dev   # watch mode: rebuilds and restarts on file changes
npm run build # one-off TypeScript compile
npm start     # run the compiled server

Troubleshooting

Error: Cannot find module '.../index.js'

If you see an error like:

Error: Cannot find module '/path/to/mcp-graphql-bridge/index.js'

You are pointing to the wrong file. The TypeScript source must be compiled first, and the entry point is in the dist/ folder:

Correct path: /path/to/mcp-graphql-bridge/dist/index.js Wrong path: /path/to/mcp-graphql-bridge/index.js

Fix:

1. Ensure you ran npm run build (creates the dist/ folder)
2. Update your MCP configuration to use the full path ending in /dist/index.js

Schema introspection fails

If the server starts but shows "Schema introspection failed", your GraphQL API may have introspection disabled in production. Use the curl command in step 3 of Setup to pre-generate a schema-introspection.json file.

Tools not appearing in Claude Code

1. Run claude mcp list to verify the server is registered
2. Run /mcp in a Claude Code session to see available tools
3. Check that your GraphQL API's environment variables are set correctly (GRAPHQL_API_URL, GRAPHQL_INTROSPECTION_URL, GRAPHQL_TOKEN) — these are optional and default to a public demo API, so if tools still aren't appearing with your own API configured, check its credentials and endpoint URLs