AI导哈

GraphQL转MCP工具

将任何GraphQL API转换为MCP工具，无需配置或代码。

  • by Docat0209
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 Docat0209/mcp-graphql

使用说明

从graphql到mcp

将任何GraphQL API转换为MCP工具-零配置，零代码。

点 graphql-to-mcp 在GraphQL端点，它通过自检为每个查询/变异自动生成一个MCP工具。适用于Claude Desktop、Cursor、Windsurf和任何MCP客户端。

快速开始

现在试试 --无需安装：

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

或者添加到Claude桌面/光标配置中：

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

就是这样。克劳德现在可以查询国家、大陆和语言。

特性

  • 零配置 --只需提供GraphQL端点URL
  • 自动自省 --自动发现所有查询和突变
  • 平面参数模式 --嵌套 input 对象被压平以获得更好的LLM精度
  • 智能截断 --对大响应进行智能修剪（数组切片+深度限制）
  • 身份验证支持 -承载令牌、API密钥（头或查询）
  • 重试逻辑 --429/5xx上的指数回退自动重试
  • 包含/排除筛选器 --仅公开您想要的操作
  • 架构缓存 --跳过重新反省 --schema-cache 更快启动
  • 突变安全性 --自动检测破坏性突变(delete*, remove*等）并警告或阻止它们

用法

命令行界面

# 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

克劳德桌面/光标配置

{
  "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模式的MCP工具
  4. 执行 --当LLM调用工具时，平面参数被重建为适当的GraphQL变量并发送到您的端点

为什么是平面模式？

LLM在填充平面键值参数方面明显优于深度嵌套的JSON对象。通过压平 InputObject 类型，我们得到：

  • 参数填充精度更高
  • 更少的幻觉嵌套结构
  • 不同LLM提供商之间的兼容性更好

选项

选项 描述 默认值
--bearer <token> 承载令牌身份验证 --
--api-key <name:value:in> API密钥授权 -
-H, --header <name:value> 自定义标头（可重复） --
--include <pattern> 仅包含匹配操作 all
--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

智能截断

GraphQL API可以返回淹没LLM上下文窗口的大负载。 graphql-to-mcp 自动：

  • 切片数组 至20个项目（元数据显示总数）
  • 修剪深度 超过5个级别（带对象/数组摘要）
  • 硬截断 50000个字符作为安全网

架构缓存

内省查询在大型模式上可能很慢。使用 --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和时间戳。如果你指向另一个端点，它会自动重新反省。

突变安全性

默认情况下， graphql-to-mcp 检测破坏性突变并在其描述中添加警告。这有助于LLM在执行之前了解风险。

检测到的模式： delete*, remove*, drop*, clear*, truncate*, destroy*, purge*, reset* 不区分大小写

模式 行为
warn （默认） 在危险突变描述前添加“DESTRUCCTIVE:”前缀
safe 从工具列表中完全排除危险突变
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采用相同的零配置方法

许可证

麻省理工学院

相关 MCP