Skip to main content
Glama
deenesjakoruzh
murilojrpereira

mcp-graphql-bridge

by murilojrpereira
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Remote

mcp-graphql-bridge

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

一个通用的 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 >= 18

设置

第 1 步：安装

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

npm install -g mcp-graphql-bridge

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

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

第 2 步：配置环境变量

变量

必需

描述

GRAPHQL_API_URL

是

用于查询和变更的端点

GRAPHQL_INTROSPECTION_URL

是

用于模式内省的端点（可以与上述相同）

GRAPHQL_TOKEN

是

用于身份验证的 Bearer 令牌

您可以在项目根目录的 .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 在生产环境中禁用了内省，或者您想要更快的启动时间时，才使用此步骤：

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

添加到 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。TypeScript 源码必须先使用 npm run build 构建，入口点位于 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 以查看可用的服务器和工具。

可用工具

工具

描述

query__<name>

每个 GraphQL 查询字段对应一个工具

mutation__<name>

每个 GraphQL 变更字段对应一个工具

execute_graphql

通用后备工具——运行任何查询或变更

get_type_details

探索特定 GraphQL 类型的字段

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

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 协议使用。

开发

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

故障排除

错误：找不到模块 '.../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 failed”，则您的 GraphQL API 可能在生产环境中禁用了内省。请使用设置第 3 步中的 curl 命令预生成 schema-introspection.json 文件。

工具未在 Claude Code 中显示

  1. 运行 claude mcp list 以验证服务器是否已注册

  2. 在 Claude Code 会话中运行 /mcp 以查看可用工具

  3. 检查是否设置了所有必需的环境变量 (GRAPHQL_API_URL, GRAPHQL_INTROSPECTION_URL, GRAPHQL_TOKEN)

Install Server
A
license - permissive license
A
quality
C
maintenance

How are these scores calculated?

Resources

Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/murilojrpereira/mcp-graphql-bridge'

If you have feedback or need assistance with the MCP directory API, please join our Discord server