{
  "markdown": "# mcp-graphql-bridge\n\n[![npm version](https://img.shields.io/npm/v/mcp-graphql-bridge.svg)](https://www.npmjs.com/package/mcp-graphql-bridge)\n[![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)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Node.js >= 20](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)\n\nA 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.\n\n## How it works\n\nOn startup the server will:\n\n1. Look for a `schema-introspection.json` file in the working directory (fast, no network call)\n2. If not found, run live introspection against `GRAPHQL_INTROSPECTION_URL`\n3. Register one tool per query (`query__<name>`) and one per mutation (`mutation__<name>`)\n4. Always register a generic `execute_graphql` fallback tool and a `get_type_details` explorer tool\n\n## Requirements\n\n- Node.js >= 20\n\n## Setup\n\n### Step 1: Install\n\n#### Option A: Install from npm (recommended)\n\n```bash\nnpm install -g mcp-graphql-bridge\n```\n\n#### Option B: Clone and build from source\n\n```bash\ngit clone https://github.com/murilojrpereira/mcp-graphql-bridge.git\ncd mcp-graphql-bridge\nnpm install\nnpm run build\n```\n\n### Step 2: Configure environment variables\n\n| Variable | Required | Description |\n|---|---|---|\n| `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. |\n| `GRAPHQL_INTROSPECTION_URL` | No | Endpoint used for schema introspection. Defaults to `GRAPHQL_API_URL` if unset. |\n| `GRAPHQL_TOKEN` | No | Bearer token for GraphQL authentication (used for query/mutation execution). Omit for public APIs. |\n| `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. |\n| `MCP_AUTH_TOKEN` | No | Bearer token required by the hosted `/mcp` HTTP endpoint when `MCP_TRANSPORT=http` |\n| `GRAPHQL_MAX_TOOLS` | No | Maximum number of query/mutation tools to register. Queries are prioritized over mutations when truncating. Default `128`. |\n| `GRAPHQL_INCLUDE_MUTATIONS` | No | Set to `false` to exclude every mutation field entirely, for a read-only deployment. Default `true`. |\n| `GRAPHQL_MAX_RETRIES` | No | Retries (0–5) for `429`/`502`/`503`/`504` responses, honoring `Retry-After` when present. Default `0` (disabled). |\n\nFor schemas with hundreds of fields (GitHub's GraphQL API has 284 root fields — 32 queries, 252\nmutations), `GRAPHQL_MAX_TOOLS` and `GRAPHQL_INCLUDE_MUTATIONS` are what keep registration bounded\nand predictable. If the cap truncates the schema, stderr logs exactly how many queries/mutations\nwere registered vs. available.\n\nNo configuration is required to try the server — with nothing set, it starts\nagainst the public demo API above and logs that it's doing so. See\n[`docs/architecture.md`](docs/architecture.md) for the full token model and\nwhy the GraphQL endpoint is fixed per deployment rather than a per-request\nparameter.\n\nYou can set these in a `.env` file at the project root:\n\n```env\nGRAPHQL_API_URL=https://your-api.example.com/graphql\nGRAPHQL_INTROSPECTION_URL=https://your-api.example.com/graphql\nGRAPHQL_TOKEN=your-bearer-token\n```\n\nOr pass them directly via the `claude mcp add` command (see below).\n\n### Step 3: (Optional) Pre-generate schema snapshot\n\nBy default the server introspects your schema live on startup — no file needed, and it\nautomatically retries at a shallower query depth if your API rejects the full-depth attempt (some\nAPIs, especially CDN-fronted ones, enforce a query depth limit). Use this step only if your API\nhas introspection disabled entirely in production, or you want faster startup times:\n\n```bash\ncurl -s -X POST https://your-api.example.com/graphql \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer your-bearer-token\" \\\n  -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 } } } } } } } } } } }\"}' \\\n  > schema-introspection.json\n```\n\nIf your API rejects this with a depth/complexity-limit error, shrink the `ofType { ... }` nesting\n(each level resolves one more `NonNull`/`List` wrapper — most real-world types need 2-3 levels;\nonly doubly-wrapped lists like `[[Int!]!]!` need more).\n\n## Adding to Claude Code\n\n### Option A: User scope (just for you)\n\n**If installed from npm:**\n```bash\nclaude mcp add --transport stdio \\\n  --env GRAPHQL_API_URL=https://your-api.example.com/graphql \\\n  --env GRAPHQL_INTROSPECTION_URL=https://your-api.example.com/graphql \\\n  --env GRAPHQL_TOKEN=your-bearer-token \\\n  graphql-bridge -- mcp-graphql-bridge\n```\n\n**If cloned from source:**\n```bash\nclaude mcp add --transport stdio \\\n  --env GRAPHQL_API_URL=https://your-api.example.com/graphql \\\n  --env GRAPHQL_INTROSPECTION_URL=https://your-api.example.com/graphql \\\n  --env GRAPHQL_TOKEN=your-bearer-token \\\n  graphql-bridge -- node /absolute/path/to/mcp-graphql-bridge/dist/index.js\n```\n\n> **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.\n\n### Option B: Project scope (shared with your team via `.mcp.json`)\n\n```bash\nclaude mcp add --transport stdio --scope project \\\n  --env GRAPHQL_API_URL=https://your-api.example.com/graphql \\\n  --env GRAPHQL_INTROSPECTION_URL=https://your-api.example.com/graphql \\\n  --env GRAPHQL_TOKEN=your-bearer-token \\\n  graphql-bridge -- mcp-graphql-bridge\n```\n\n> **Note:** Use absolute paths. All `--env` and `--transport` flags must come before the server name.\n\n### Verify the connection\n\n```bash\nclaude mcp list\n```\n\nThen in a Claude Code session, run `/mcp` to see available servers and tools.\n\n## Examples\n\nTwo worked walkthroughs — a small public schema with no configuration needed, then a large,\nreal enterprise-scale schema requiring auth and tool-count limits.\n\n### Example 1: Countries API (small schema, no auth)\n\nThis is the zero-config default — nothing to install or configure beyond the server itself.\n\n1. Add the server with no environment variables at all:\n\n   ```bash\n   claude mcp add --transport stdio graphql-countries -- mcp-graphql-bridge\n   ```\n\n2. Restart Claude Code (or run `/mcp` to confirm `graphql-countries` is connected). You should see\n   tools like `query__country`, `query__countries`, and `query__continents`.\n3. Ask Claude:\n\n   > Using graphql-countries, find the country with code \"BR\", then list its continent's other countries.\n\n   Claude calls `query__country({ code: \"BR\", __fields: \"{ name continent { code name } }\" })`,\n   then `query__continent` or `query__countries({ __fields: \"{ name }\" })` filtered by the result.\n4. Try an invalid code to see error passthrough:\n\n   > Look up the country with code \"ZZZ\".\n\n   Returns the GraphQL API's own error text — the bridge passes it through rather than masking it.\n\n### Example 2: GitHub GraphQL API (large schema, auth + tool limits)\n\nGitHub's GraphQL API has **284 root fields** (32 queries, 252 mutations) — far more than the\n`GRAPHQL_MAX_TOOLS` default of 128, and it needs a token for every request, including\nintrospection (unlike GitHub's REST API, which allows some anonymous reads).\n\n1. Add the server, scoped to read-only access:\n\n   ```bash\n   export GH_TOKEN=ghp_your_personal_access_token  # or: source a gitignored .env file first\n\n   claude mcp add --transport stdio graphql-github \\\n     --env GRAPHQL_API_URL=https://api.github.com/graphql \\\n     --env GRAPHQL_INTROSPECTION_URL=https://api.github.com/graphql \\\n     --env GRAPHQL_TOKEN=$GH_TOKEN \\\n     --env GRAPHQL_INCLUDE_MUTATIONS=false \\\n     graphql-bridge -- mcp-graphql-bridge\n   ```\n\n   `GRAPHQL_INCLUDE_MUTATIONS=false` registers all 32 (read-only) queries and zero mutations —\n   comfortably under the cap, and a meaningfully safer default for an AI agent than exposing all\n   252 write operations.\n2. Ask Claude:\n\n   > Using graphql-github, look up the repository facebook/react and tell me its star count.\n\n   Claude calls\n   `query__repository({ owner: \"facebook\", name: \"react\", __fields: \"{ name stargazerCount }\" })`.\n3. To also reach mutations, drop `GRAPHQL_INCLUDE_MUTATIONS=false` and raise the cap\n   (`GRAPHQL_MAX_TOOLS=400`), understanding that this exposes write access to your GitHub account\n   scoped to whatever permissions your token has.\n\n## Available tools\n\n| Tool | Description |\n|---|---|\n| `query__<name>` | One tool per GraphQL query field |\n| `mutation__<name>` | One tool per GraphQL mutation field |\n| `execute_graphql` | Generic fallback — run any query or mutation (mutations rejected if `GRAPHQL_INCLUDE_MUTATIONS=false`) |\n| `get_type_details` | Explore fields of a specific GraphQL type |\n\nAll 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.\n\n**Per-call auth override**: every tool (including `execute_graphql`) also accepts `bearer_token`\nand `custom_headers` arguments. If provided, they override `GRAPHQL_TOKEN`/no-auth for that single\nrequest only, letting Claude switch credentials per call without restarting the server.\n\n## Security\n\n- **The target API is fixed per deployment, never a per-request parameter.** Individual tool calls\n  can override *credentials* (`bearer_token`, `custom_headers`) but never the destination host —\n  `GRAPHQL_API_URL` is set once at deployment time. A shared server that let callers redirect it to\n  an arbitrary destination would be a Server-Side Request Forgery (SSRF) primitive; this design\n  rules that out by construction.\n- **Configured and per-call secrets are redacted from every response** before it reaches the\n  calling LLM.\n- **`GRAPHQL_INCLUDE_MUTATIONS=false`** excludes every mutation field from registration for a\n  genuinely read-only deployment — a meaningful trust boundary GraphQL's type system already\n  encodes, rather than relying on token scope alone. This is enforced for `execute_graphql` too:\n  it parses the query and rejects any mutation when this flag is off, rather than only omitting\n  the convenience `mutation__*` tools while leaving the generic fallback able to run anything.\n- **`MCP_AUTH_TOKEN`** gates the HTTP transport's `/mcp` endpoint for public-routable deployments;\n  requests are capped at 10MB.\n\nSee [`docs/architecture.md`](docs/architecture.md) for the full design rationale and\n[`SECURITY.md`](SECURITY.md) to report a vulnerability.\n\n## Docker\n\n### Build the image\n\n```bash\ndocker build -t mcp-graphql-bridge .\n```\n\n### Add to Claude Code via Docker\n\n```bash\nclaude mcp add --transport stdio \\\n  --env GRAPHQL_API_URL=https://your-api.example.com/graphql \\\n  --env GRAPHQL_INTROSPECTION_URL=https://your-api.example.com/graphql \\\n  --env GRAPHQL_TOKEN=your-bearer-token \\\n  graphql-bridge -- docker run -i --rm \\\n  -e GRAPHQL_API_URL -e GRAPHQL_INTROSPECTION_URL -e GRAPHQL_TOKEN \\\n  mcp-graphql-bridge\n```\n\n> **Note:** The `-i` flag (no `-t`) is required — it keeps stdin open for the MCP stdio protocol.\n\n## HTTP deployment\n\nFor hosted MCP access, run the HTTP transport instead of stdio:\n\n```bash\ndocker build -f Dockerfile.http -t mcp-graphql-bridge-http .\ndocker run --rm -p 8080:8080 \\\n  -e GRAPHQL_API_URL=https://your-api.example.com/graphql \\\n  -e GRAPHQL_INTROSPECTION_URL=https://your-api.example.com/graphql \\\n  -e GRAPHQL_TOKEN=your-bearer-token \\\n  mcp-graphql-bridge-http\n```\n\nHealth checks are available at `/health`; MCP requests are served at `/mcp`.\n\nFor public-routable deployments, set `MCP_AUTH_TOKEN` and configure clients to send `Authorization: Bearer <token>` to `/mcp`.\n\nSee [`docs/deployment.md`](docs/deployment.md) for AWS, Cloudflare, and other container hosting options.\n\n## Development\n\n```bash\nnpm run dev   # watch mode: rebuilds and restarts on file changes\nnpm run build # one-off TypeScript compile\nnpm start     # run the compiled server\n```\n\n## Troubleshooting\n\n### Error: Cannot find module '.../index.js'\n\nIf you see an error like:\n```\nError: Cannot find module '/path/to/mcp-graphql-bridge/index.js'\n```\n\nYou are pointing to the wrong file. The TypeScript source must be compiled first, and the entry point is in the `dist/` folder:\n\n**Correct path:** `/path/to/mcp-graphql-bridge/dist/index.js`\n**Wrong path:** `/path/to/mcp-graphql-bridge/index.js`\n\n**Fix:**\n1. Ensure you ran `npm run build` (creates the `dist/` folder)\n2. Update your MCP configuration to use the full path ending in `/dist/index.js`\n\n### Schema introspection fails\n\nIf 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.\n\n### Tools not appearing in Claude Code\n\n1. Run `claude mcp list` to verify the server is registered\n2. Run `/mcp` in a Claude Code session to see available tools\n3. 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\n",
  "bytes": 14356,
  "sha": "534e7bbff4eddb57a0ecceec45e369236d5ff75bb178d2c176a0f684e56ba02b",
  "repo_slug": "murilojrpereira/mcp-graphql-bridge",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_murilojrpereira_mcp_graphql_br_1f1cd007/readme"
}