mcp-graphql-bridge

# mcp-graphql-bridge

[![npm version](https://img.shields.io/npm/v/mcp-graphql-bridge.svg)](https://www.npmjs.com/package/mcp-graphql-bridge)
[![CI](https://github.com/murilojrpereira/mcp-graphql-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/murilojrpereira/mcp-graphql-bridge/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Node.js >= 20](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)

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)

```bash
npm install -g mcp-graphql-bridge
```

#### Option B: Clone and build from source

```bash
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](https://countries.trevorblades.com/graphql)) 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` |
| `GRAPHQL_MAX_TOOLS` | No | Maximum number of query/mutation tools to register. Queries are prioritized over mutations when truncating. Default `128`. |
| `GRAPHQL_INCLUDE_MUTATIONS` | No | Set to `false` to exclude every mutation field entirely, for a read-only deployment. Default `true`. |
| `GRAPHQL_MAX_RETRIES` | No | Retries (0–5) for `429`/`502`/`503`/`504` responses, honoring `Retry-After` when present. Default `0` (disabled). |

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`](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:

```env
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:

```bash
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:**
```bash
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:**
```bash
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`)

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

```bash
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:

   ```bash
   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:

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

| 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 (mutations rejected if `GRAPHQL_INCLUDE_MUTATIONS=false`) |
| `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 }`