mcp-graphql-bridge

mcp-graphql-bridge

一个通用的 MCP（Model Context Protocol）服务，可将任意 GraphQL API 接入 Claude Code。它会内省你的 GraphQL 架构，并将每个查询和变更都作为独立工具公开，让 Claude 能够直接与你的 API 交互。

工作原理

启动时，服务会：

1. 在工作目录中查找 schema-introspection.json 文件（速度快，无需网络请求）
2. 如果找不到，则对 GRAPHQL_INTROSPECTION_URL 执行实时内省
3. 为每个查询注册一个工具（query__<name>），并为每个变更注册一个工具（mutation__<name>）
4. 始终注册一个通用的 execute_graphql 备用工具和一个 get_type_details 浏览工具

要求

• Node.js >= 20

设置

步骤 1：安装

选项 A：从 npm 安装（推荐）

npm install -g mcp-graphql-bridge

选项 B：克隆并从源代码构建

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

步骤 2：配置环境变量

变量	必需	描述
GRAPHQL_API_URL	否	查询和变更使用的端点。如果未设置，默认使用公共演示 API（countries.trevorblades.com）；实际使用时请替换为你自己的端点。
GRAPHQL_INTROSPECTION_URL	否	架构内省使用的端点。如果未设置，默认使用 GRAPHQL_API_URL。
GRAPHQL_TOKEN	否	GraphQL 身份验证所需的 Bearer 令牌（用于执行查询/变更）。公共 API 无需设置。
GRAPHQL_INTROSPECTION_TOKEN	否	架构内省所需的 Bearer 令牌；如果内省所需凭据与执行操作所需凭据不同（例如使用独立的架构注册表），则需要设置。如果未设置，默认使用 GRAPHQL_TOKEN。
MCP_AUTH_TOKEN	否	当 MCP_TRANSPORT=http 时，托管的 /mcp HTTP 端点所需的 Bearer 令牌
GRAPHQL_MAX_TOOLS	否	要注册的查询/变更工具数量上限。截断时优先保留查询。默认值为 128。
GRAPHQL_INCLUDE_MUTATIONS	否	设置为 false 可完全排除所有变更字段，用于只读部署。默认值为 true。
GRAPHQL_MAX_RETRIES	否	对 429/502/503/504 响应的重试次数（0–5）；如果存在 Retry-After，则会遵循该值。默认值为 0（禁用）。

对于包含数百个字段的架构（GitHub 的 GraphQL API 有 284 个根字段——32 个查询、252 个变更），GRAPHQL_MAX_TOOLS 和 GRAPHQL_INCLUDE_MUTATIONS 可确保注册数量有上限且可预测。 如果上限导致架构被截断，stderr 会准确记录已注册与可用的查询/变更数量。

无需任何配置即可试用此服务——未设置任何变量时，它会连接到上述公共演示 API 并记录相关信息。完整的令牌模型，以及为什么 GraphQL 端点是为每个部署固定设置而不是作为每次请求的参数，请参阅 docs/architecture.md。

你可以在项目根目录的 .env 文件中设置这些变量：

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

也可以通过 claude mcp add 命令直接传入（见下文）。

步骤 3：（可选）预生成架构快照

默认情况下，服务会在启动时实时内省你的架构——无需文件；如果 API 拒绝完整深度的请求，它会自动改用较浅的查询深度重试（有些 API，尤其是由 CDN 提供服务的 API，会限制查询深度）。只有在生产环境中完全禁用了 API 内省，或你希望加快启动速度时，才使用此步骤：

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

如果 API 因深度／复杂度限制错误而拒绝此请求，请减少 ofType { ... } 的嵌套层数（每一层会解析一个额外的 NonNull／List 包装器——大多数实际类型需要 2-3 层；只有像 [[Int!]!]! 这样的双重包装列表才需要更多层）。

添加到 Claude Code

选项 A：用户范围（仅供你使用）

如果通过 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

如果从源代码克隆：

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

重要： 请务必使用 mcp-graphql-bridge/dist/index.js（编译后的输出），而不是 mcp-graphql-bridge/index.js。必须先使用 npm run build 构建 TypeScript 源代码，入口点位于 dist/ 文件夹中。

选项 B：项目范围（通过 .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

注意： 请使用绝对路径。所有 --env 和 --transport 标志都必须放在服务名称之前。

验证连接

claude mcp list

然后在 Claude Code 会话中运行 /mcp，查看可用的服务和工具。

MCP Registry

此服务已发布到官方 MCP Registry，名称为 io.github.murilojrpereira/mcp-graphql-bridge，因此浏览该注册表的 MCP 客户端可以发现并从中安装此服务。

示例

以下是两个完整的演示流程——先介绍一个无需配置的小型公共架构，再介绍一个需要身份验证和工具数量限制的大型企业级架构。

示例 1：Countries API（小型架构，无需身份验证）

这是零配置的默认用法——除了服务本身，无需安装或配置其他内容。

1. 添加服务，无需设置任何环境变量：

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

2. 重启 Claude Code（或运行 /mcp，确认 graphql-countries 已连接）。你应该会看到 query__country、query__countries 和 query__continents 等工具。

3. 向 Claude 提问：

   使用 graphql-countries，查找代码为 "BR" 的国家，然后列出其所属大洲的其他国家。

   Claude 会调用 query__country({ code: "BR", __fields: "{ name continent { code name } }" })， 然后调用 query__continent 或 query__countries({ __fields: "{ name }" })，并根据返回结果进行筛选。

4. 尝试使用无效代码，查看错误透传：

   查找代码为 "ZZZ" 的国家。

   返回 GraphQL API 自身的错误文本——桥接服务会直接传递错误，而不是将其隐藏。

示例 2：GitHub GraphQL API（大型架构，身份验证 + 工具限制）

GitHub 的 GraphQL API 有 284 个根字段（32 个查询、252 个变更）——远超 GRAPHQL_MAX_TOOLS 默认值 128；而且每个请求都需要令牌，包括内省（与允许部分匿名读取的 GitHub REST API 不同）。

1. 添加服务，并将其限定为只读访问：

   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 会注册全部 32 个（只读）查询，不注册任何变更——远低于上限；与向 AI Agent 暴露全部 252 个写入操作相比，这也是更安全且更有意义的默认设置。

2. 向 Claude 提问：

   使用 graphql-github，查找 facebook/react 仓库，并告诉我它的星标数量。

   Claude 会调用 query__repository({ owner: "facebook", name: "react", __fields: "{ name stargazerCount }" })。

3. 若还要使用变更操作，请移除 GRAPHQL_INCLUDE_MUTATIONS=false 并提高上限 （GRAPHQL_MAX_TOOLS=400），同时注意，这将开放对 GitHub 账户的写入访问权限，具体范围取决于令牌拥有的权限。

可用工具

工具	描述
query__<name>	每个 GraphQL 查询字段对应一个工具
mutation__<name>	每个 GraphQL 变更字段对应一个工具
execute_graphql	通用备用工具——运行任意查询或变更（当 GRAPHQL_INCLUDE_MUTATIONS=false 时会拒绝变更）
get_type_details	查看特定 GraphQL 类型的字段

所有按操作提供的工具都接受一个特殊的 __fields 参数，可用于提供自定义 GraphQL 选择集（例如 { id name status }）。如果省略，则只返回标量字段。

单次调用身份验证覆盖：每个工具（包括 execute_graphql）也接受 bearer_token 和 custom_headers 参数。若提供这些参数，它们仅对该次请求覆盖 GRAPHQL_TOKEN/无身份验证配置，让 Claude 无需重启服务即可按调用切换凭据。

安全性

• 每次部署的目标 API 都是固定的，不能作为单次请求参数传入。 单独的工具调用可以覆盖凭据（bearer_token、custom_headers），但不能更改目标主机——GRAPHQL_API_URL 在部署时设置一次。允许调用者将共享服务重定向到任意目标，会形成服务器端请求伪造（SSRF）攻击原语；此设计从根本上杜绝了这种情况。
• 在配置中设置的密钥和单次调用的密钥，会在每个响应发送给调用 LLM 前进行脱敏。
• GRAPHQL_INCLUDE_MUTATIONS=false 会在注册时排除所有变更字段，实现真正的只读部署——这是 GraphQL 类型系统本身已编码的重要信任边界，而不是仅依赖令牌权限范围。此限制也适用于 execute_graphql：它会解析查询，并在此标志关闭时拒绝任何变更，而不仅仅是省略便捷的 mutation__* 工具、却让通用备用工具仍能执行任意操作。
• MCP_AUTH_TOKEN 为面向公共网络的部署保护 HTTP 传输的 /mcp 端点；请求大小上限为 10MB。

完整的设计依据请参阅 docs/architecture.md，如需报告漏洞，请参阅 SECURITY.md。

Docker

构建镜像

docker build -t mcp-graphql-bridge .

通过 Docker 添加到 Claude Code

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

注意： 必须使用 -i 标志（不使用 -t）——它会保持 stdin 打开，以供 MCP stdio 协议使用。

HTTP 部署

如需托管式 MCP 访问，请运行 HTTP 传输，而非 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 提供运行状况检查；MCP 请求由 /mcp 处理。

对于面向公共网络的部署，请设置 MCP_AUTH_TOKEN，并将客户端配置为向 /mcp 发送 Authorization: Bearer <token>。

有关 AWS、Cloudflare 及其他容器托管选项，请参阅 docs/deployment.md。

开发

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

有关贡献指南和维护者发布流程，请参阅 CONTRIBUTING.md。

故障排除

错误：Cannot find module '.../index.js'

如果看到类似以下错误：

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

你指向了错误的文件。必须先编译 TypeScript 源码，入口文件位于 dist/ 文件夹中：

正确路径： /path/to/mcp-graphql-bridge/dist/index.js 错误路径： /path/to/mcp-graphql-bridge/index.js

修复方法：

1. 确保已运行 npm run build（此命令会创建 dist/ 文件夹）
2. 更新 MCP 配置，使用以 /dist/index.js 结尾的完整路径

Schema introspection fails

如果服务已启动，但显示“Schema introspection failed”，你的 GraphQL API 可能在生产环境中禁用了内省。请使用 Setup 的第 3 步中的 curl 命令，预先生成 schema-introspection.json 文件。

Claude Code 中未显示工具

1. 运行 claude mcp list，确认已注册服务
2. 在 Claude Code 会话中运行 /mcp，查看可用工具
3. 检查 GraphQL API 的环境变量是否设置正确（GRAPHQL_API_URL、GRAPHQL_INTROSPECTION_URL、GRAPHQL_TOKEN）——这些变量均为可选项，默认使用公共演示 API。因此，如果配置了自己的 API 后仍未显示工具，请检查其凭据和端点 URL