Graphql To Mcp

graphql-to-mcp

将任意 GraphQL API 转换为 MCP 工具——无需配置，无需编写代码。

将 graphql-to-mcp 指向一个 GraphQL 端点，它就会通过内省自动为每个查询和变更生成一个 MCP 工具。兼容 Claude Desktop、Cursor、Windsurf 和任意 MCP 客户端。

快速开始

立即试用——无需安装：

npx graphql-to-mcp https://countries.trevorblades.com/graphql

或者添加到 Claude Desktop / Cursor 配置中：

{
  "mcpServers": {
    "countries": {
      "command": "npx",
      "args": ["-y", "graphql-to-mcp", "https://countries.trevorblades.com/graphql"]
    }
  }
}

就是这么简单。现在 Claude 可以查询国家、大洲和语言了。

功能

• 无需配置——只需提供 GraphQL 端点 URL
• 自动内省——自动发现所有查询和变更
• 扁平参数架构——将嵌套的 input 对象扁平化，以提高大模型的准确性
• 智能截断——智能精简大型响应（切片数组 + 限制深度）
• 支持身份验证——Bearer 令牌、API 密钥（通过标头或查询参数传递）
• 重试逻辑——遇到 429/5xx 时自动重试，并采用指数退避
• 包含/排除过滤器——只公开你需要的操作
• 架构缓存——使用 --schema-cache 跳过重新内省，加快启动速度
• 变更安全性——自动检测有破坏性的变更（delete*、remove* 等），并发出警告或阻止操作

用法

CLI

# Public API (no auth)
npx graphql-to-mcp https://countries.trevorblades.com/graphql

# With bearer token
npx graphql-to-mcp https://api.github.com/graphql --bearer ghp_xxxxx

# With API key
npx graphql-to-mcp https://api.example.com/graphql --api-key "X-API-Key:your-key:header"

# Filter operations
npx graphql-to-mcp https://api.example.com/graphql --include "get*" --exclude "internal*"

# With prefix (avoid name collisions when using multiple APIs)
npx graphql-to-mcp https://api.example.com/graphql --prefix myapi

# Cache schema locally for faster restarts
npx graphql-to-mcp https://api.example.com/graphql --schema-cache ./schema.json

# Force re-introspection (ignore cache)
npx graphql-to-mcp https://api.example.com/graphql --schema-cache ./schema.json --force-refresh

# Block destructive mutations (delete*, remove*, etc.)
npx graphql-to-mcp https://api.example.com/graphql --mutation-safety safe

Claude Desktop / Cursor 配置

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y", "graphql-to-mcp",
        "https://api.github.com/graphql",
        "--bearer", "ghp_xxxxx",
        "--prefix", "github"
      ]
    }
  }
}

编程方式

import { createServer } from "graphql-to-mcp";

const server = await createServer({
  endpoint: "https://api.example.com/graphql",
  auth: { type: "bearer", token: "xxx" },
  include: ["getUser", "listUsers"],
});

工作原理

1. 内省——通过内省查询获取 GraphQL 架构
2. 扁平化——将嵌套的 InputObject 类型扁平化为简单的键值参数（例如，input.name → input_name）
3. 生成——将每个查询/变更转换为一个带有扁平 JSON Schema 的 MCP 工具
4. 执行——大模型调用工具时，将扁平参数重组为正确的 GraphQL 变量，并发送到你的端点

为什么使用扁平架构？

与深度嵌套的 JSON 对象相比，大模型更擅长填写扁平的键值参数。通过扁平化 InputObject 类型，我们可以实现：

• 更高的参数填写准确率
• 更少虚构的嵌套结构
• 更好地兼容不同的大模型提供商

选项

选项	说明	默认值
--bearer <token>	Bearer 令牌身份验证	—
--api-key <name:value:in>	API 密钥身份验证	—
-H, --header <name:value>	自定义标头（可重复使用）	—
--include <pattern>	仅包含匹配的操作	全部
--exclude <pattern>	排除匹配的操作	无
--prefix <name>	工具名称前缀	—
--timeout <ms>	请求超时时间	30000
--max-retries <n>	遇到 429/5xx 时重试	3
--transport <stdio|sse>	MCP 传输方式	stdio
--schema-cache <path>	保存/加载内省缓存	—
--force-refresh	忽略缓存，重新内省	false
--mutation-safety <mode>	warn | safe | unrestricted	warn

智能截断

GraphQL API 可能返回大量数据，超出大模型上下文窗口的承载能力。graphql-to-mcp 会自动：

• 切片数组，保留 20 个项目（并提供显示总数的元数据）
• 精简深度，超过 5 层时进行精简（并提供对象/数组摘要）
• 硬性截断，最多保留 50K 个字符，作为安全措施

架构缓存

大型架构的内省查询可能耗时较长。使用 --schema-cache 在本地保存内省结果：

# First run: introspects and saves to cache
npx graphql-to-mcp https://api.example.com/graphql --schema-cache ./schema.json

# Subsequent runs: loads from cache (instant startup)
npx graphql-to-mcp https://api.example.com/graphql --schema-cache ./schema.json

# Force re-introspection when the API schema changes
npx graphql-to-mcp https://api.example.com/graphql --schema-cache ./schema.json --force-refresh

缓存文件会保存端点 URL 和时间戳。如果你指向不同的端点，程序会自动重新内省。

Mutation 安全性

默认情况下，graphql-to-mcp 会检测具有破坏性的 Mutation，并在其描述中添加警告。这有助于大模型在执行前了解风险。

检测模式：delete*、remove*、drop*、clear*、truncate*、destroy*、purge*、reset*（不区分大小写）。

模式	行为
warn（默认）	在危险 Mutation 的描述前添加“DESTRUCTIVE:”前缀
safe	将危险 Mutation 完全排除在工具列表之外
unrestricted	不进行过滤或警告（此前的行为）

# Safe mode: only expose read queries + non-destructive mutations
npx graphql-to-mcp https://api.example.com/graphql --mutation-safety safe

# Unrestricted: expose everything (use with caution)
npx graphql-to-mcp https://api.example.com/graphql --mutation-safety unrestricted

也可用于 REST API

与 mcp-openapi 搭配使用，让 Claude 能够访问 REST 和 GraphQL API：

{
  "mcpServers": {
    "github-graphql": {
      "command": "npx",
      "args": ["-y", "graphql-to-mcp", "https://api.github.com/graphql", "--bearer", "ghp_xxx", "--prefix", "gh"]
    },
    "petstore-rest": {
      "command": "npx",
      "args": ["-y", "mcp-openapi", "https://petstore3.swagger.io/api/v3/openapi.json"]
    }
  }
}

相关项目

• mcp-openapi — 面向 REST/OpenAPI API 的相同零配置方案

许可证

MIT