使用说明
GraphQL MCP服务器
将任何GraphQL API转换为零编码的Claude Code工具
一个通用的模型上下文协议（MCP）服务器，可以自动转换您的 .graphql 将查询文件转换为Claude可以使用的工具。使用 任何 GraphQL API-GitHub、Shopify、Hasura或您自己的。
它的作用
- 将其指向任何GraphQL端点 （GitHub、Shopify、Hasura等）
- 掉落
.graphql查询文件夹中的文件 - 自动将它们作为Claude代码工具公开
无需MCP编码，只需编写GraphQL查询并配置端点即可。
为什么使用这个？
代币节省
GraphQL允许你只请求你需要的字段，大大减少了响应大小：
| API类型 | 响应大小 | 使用的令牌 | 节省 |
|---|---|---|---|
| 剩余 | 168kb | ~42000 | - |
| GraphQL（最小） | 500字节 | ~125 | 99.7% |
| GraphQL（目标） | 5 KB | ~1250 | 97% |
便利
不用为每个API编写自定义MCP服务器代码，只需：
- 配置端点
- 编写GraphQL查询
- 完成
安装
从源代码克隆和构建：
git clone https://github.com/Chakit22/graphql-mcp-server.git
cd graphql-mcp-server
npm install
npm run build
快速开始
1.创建项目目录
mkdir my-graphql-mcp
cd my-graphql-mcp
mkdir operations
2.创建 config.json
{
"endpoint": "https://api.github.com/graphql",
"operationsDir": "./operations",
"headers": {
"Authorization": "Bearer YOUR_TOKEN_HERE"
},
"name": "my-mcp-server",
"version": "1.0.0"
}
3.创建GraphQL查询文件
创建 operations/GetRepository.graphql:
# @description Get repository information
query GetRepository($owner: String!, $name: String!) {
repository(owner: $owner, name: $name) {
name
description
stargazerCount
url
}
}
4.配置克劳德代码
添加 ~/.config/claude-code/mcp_settings.json:
{
"mcpServers": {
"my-graphql-mcp": {
"command": "node",
"args": ["/path/to/graphql-mcp-server/dist/index.js"],
"env": {
"GRAPHQL_MCP_CONFIG": "/path/to/my-graphql-mcp/config.json"
}
}
}
}
5.重新启动克劳德代码
MCP服务器将自动将GraphQL操作作为工具加载。
配置参考
config.json
| 字段 | 类型 | 必填 | 描述 |
|---|---|---|---|
endpoint |
字符串 | 是 | GraphQL API端点URL |
operationsDir |
string | 是 | 目录路径包含 .graphql 文件 |
headers |
object | No | HTTP标头（例如，授权） |
name |
string | 否 | MCP服务器名称（默认：“graphql-MCP服务器”） |
version |
string | 否 | MCP服务器版本（默认：“1.0.0”） |
环境变量
GRAPHQL_MCP_CONFIG：配置文件的路径（默认值：./config.json)
编写GraphQL操作
基本查询
# @description Brief description shown in Claude
query OperationName($param1: String!, $param2: Int) {
field1
field2
}
特性
@description评论：出现在Claude的工具列表中- 变量：自动成为刀具参数
- 型支座：字符串、整数、浮点数、布尔值、ID、数组
- 必填参数：以结尾的变量
!需要
示例：搜索查询
# @description Search repositories by keyword
query SearchRepos($query: String!, $limit: Int!) {
search(query: $query, type: REPOSITORY, first: $limit) {
repositoryCount
edges {
node {
... on Repository {
name
url
stargazerCount
}
}
}
}
}
例子
SpaceX API（无需验证-请先尝试！）
非常适合测试-无需API密钥即可立即工作。
配置：
{
"endpoint": "https://spacex-production.up.railway.app/",
"operationsDir": "./operations",
"name": "spacex-mcp"
}
可用操作：
GetRockets-获取所有SpaceX火箭GetLaunches-获取最新发布
📁 完整示例： examples/spacex/
GitHub API
配置：
{
"endpoint": "https://api.github.com/graphql",
"operationsDir": "./operations",
"headers": {
"Authorization": "Bearer ghp_YOUR_TOKEN"
}
}
可用操作：
GetRepository-获取回购详细信息SearchRepositories-按关键字搜索仓库
📁 完整示例： examples/github/
Shopify API
配置：
{
"endpoint": "https://YOUR_STORE.myshopify.com/admin/api/2024-01/graphql.json",
"operationsDir": "./operations",
"headers": {
"X-Shopify-Access-Token": "YOUR_TOKEN"
}
}
可用操作：
GetProducts-获取带分页的产品
📁 完整示例： examples/shopify/
Hasura/自托管
配置：
{
"endpoint": "http://localhost:8080/v1/graphql",
"operationsDir": "./operations",
"headers": {
"x-hasura-admin-secret": "YOUR_SECRET"
}
}
运作原理
┌──────────┐ ┌──────────────┐ ┌────────────────┐
│ Claude │────▶│ MCP Server │────▶│ GraphQL API │
│ Code │ │ (this tool) │ │ (any endpoint) │
└──────────┘ └──────────────┘ └────────────────┘
│
▼
Loads *.graphql
from operations/
- MCP服务器读取所有
.graphql文件来自operationsDir - 将每个都注册为Claude Code工具
- 当Claude调用工具时：
- 将GraphQL查询发送到配置的端点
- 从Claude传递变量
- 返回对Claude的响应
发展
# Install dependencies
npm install
# Build TypeScript
npm run build
# Run in dev mode (with auto-reload)
npm run dev
# Run built version
npm start
故障排除
“找不到配置文件”
- 检查
GRAPHQL_MCP_CONFIG环境变量 - 确保
config.json存在于当前目录或指定路径中
“未找到.graphql文件”
- 检查
operationsDir配置中的路径 - 确保
.graphql或.gql该目录中存在文件
“HTTP 401未经授权”
- 检查
headers.Authorization在配置中 - 验证您的API令牌是否有效
“响应中的GraphQL错误”
- 首先直接针对API测试您的查询
- 检查变量类型是否与架构匹配
- 验证必填字段是否存在
需求
- Node.js 16+
- GraphQL API端点
- 有效的身份验证凭据（如果API要求）
许可证
麻省理工学院
贡献
欢迎投稿！请打开问题或PR。
