GraphQL MCP 服务器

一个强类型的 TypeScript 模型上下文协议 (MCP) 服务器，通过 Claude AI 提供对任何 GraphQL API 的无缝访问。

特性

• 强类型: 使用 TypeScript 构建，以提高代码质量和类型安全
• 动态 GraphQL 集成: 连接到任何 GraphQL API，并自动生成工具
• Schema 自省: 自动发现并暴露所有 GraphQL 操作作为工具
• 完全 Mutation 支持: 一流的 GraphQL mutation 支持，并进行适当的处理
• 查询 & Mutation 白名单: 可选的白名单，用于控制暴露哪些 GraphQL 操作
• 丰富的类型支持: 正确处理复杂的 GraphQL 类型、输入对象和变量
• MCP 标准兼容: 遵循模型上下文协议格式，实现无缝 Claude 集成
• 智能查询生成: 构建高效的 GraphQL 查询，并进行适当的字段选择
• 身份验证支持: 简单的 API 密钥身份验证

仓库结构

graphql-mcp/
├── src/
│   └── graphql-mcp-server.ts     # 主要服务器实现 (TypeScript)
├── dist/                         # 编译后的 JavaScript (生成)
├── docs/
│   ├── GETTING_STARTED.md         # 设置和使用指南
│   ├── PROJECT_STATUS.md          # 当前项目状态
│   └── TECHNICAL.md               # 技术文档
├── .env.development               # 环境变量
├── .env.sample                    # 示例环境变量模板
├── claude_desktop_sample_config.json  # 示例 Claude Desktop 配置
├── package.json                   # 项目依赖
├── tsconfig.json                  # TypeScript 配置
├── run-graphql-mcp.sh             # 运行服务器的脚本
└── README.md                      # 本文件

前提条件

• Node.js 18 或更高版本
• TypeScript 5.x 或更高版本
• 支持 MCP 的 Claude Desktop
• 一个 GraphQL API 端点 (如果未指定，则默认为 Countries API)

安装

选项 1: 从 npm

# 全局安装
npm install -g graphql-mcp

# 运行服务器
graphql-mcp-server

选项 2: 克隆仓库

# 克隆仓库
git clone https://github.com/ctkadvisors/graphql-mcp.git
cd graphql-mcp

# 安装依赖
npm install

# 运行服务器
npm start

快速开始

1. 设置环境变量

复制示例 env 文件，并使用您的 GraphQL API 详细信息更新它：

cp .env.sample .env.development

编辑 .env.development，填写您的 GraphQL API 端点和可选的 API 密钥。

2. 构建并运行

首先编译 TypeScript 代码：

npm install
npm run build

然后运行服务器：

node dist/graphql-mcp-server.js

或者使用提供的脚本，该脚本可以一步编译和运行：

./run-graphql-mcp.sh

3. Claude Desktop 集成

将此服务器添加到您的 Claude Desktop 配置：

1. 使用示例配置作为模板：

   cp claude_desktop_sample_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json
   

2. 编辑配置并更新路径以指向您的安装：

   {
     "mcpServers": {
       "graphql": {
         "command": "node",
         "args": ["/absolute/path/to/dist/graphql-mcp-server.js"],
         "env": {
           "GRAPHQL_API_ENDPOINT": "https://your-graphql-api.com/graphql",
           "GRAPHQL_API_KEY": "your-api-key-if-needed",
           "WHITELISTED_QUERIES": "[\"countries\",\"continent\",\"languages\"]"
         }
       }
     }
   }
   

3. 重新启动 Claude Desktop 以连接到服务器

您现在应该在 Claude Desktop 中看到 GraphQL 操作作为可用工具！

操作白名单

出于安全或性能原因，您可能希望限制哪些 GraphQL 操作（查询和 mutation）暴露给 Claude。 有两种方法可以控制访问：

1. 启用/禁用 Mutation: 默认情况下，为了安全起见，所有 mutation 均已禁用。 要启用 mutation：

"env": {
  "GRAPHQL_API_ENDPOINT": "https://example-graphql-api.com/graphql",
  "ENABLE_MUTATIONS": "true"
}

2. 操作白名单: 您可以指定哪些特定操作应该可用：

"env": {
  "GRAPHQL_API_ENDPOINT": "https://example-graphql-api.com/graphql",
  "ENABLE_MUTATIONS": "true",
  "WHITELISTED_QUERIES": "[\"countries\",\"continent\",\"languages\"]",
  "WHITELISTED_MUTATIONS": "[\"createUser\",\"updateProfile\"]"
}

白名单可以用两种格式指定：

• 作为 JSON 数组字符串（如上所示）："[\"query1\",\"query2\"]"
• 作为逗号分隔的列表："query1,query2,query3"

重要提示: 白名单值必须是字符串，而不是实际的 JSON 数组对象。 环境变量始终作为字符串传递，因此您需要正确转义 JSON 字符串中的引号，如上所示。

Claude Desktop 配置中正确格式的示例:

"graphql-api": {
  "command": "node",
  "args": [
    "/Users/username/Projects/graphql-mcp/dist/graphql-mcp-server.js"
  ],
  "env": {
    "GRAPHQL_API_ENDPOINT": "https://example-graphql-api.com/graphql",
    "NODE_ENV": "development",
    "DEBUG": "true",
    "ENABLE_MUTATIONS": "true",
    "WHITELISTED_QUERIES": "[\"getUser\",\"getProducts\",\"getOrders\"]",
    "WHITELISTED_MUTATIONS": "[\"createOrder\",\"updateProfile\"]"
  }
}

要避免的常见错误:

// 错误 - 将不起作用！
"WHITELISTED_QUERIES": ["getUser", "getProducts"],
"WHITELISTED_MUTATIONS": ["createOrder", "updateProfile"]

// 正确
"WHITELISTED_QUERIES": "[\"getUser\",\"getProducts\"]",
"WHITELISTED_MUTATIONS": "[\"createOrder\",\"updateProfile\"]"

如果未为特定操作类型提供白名单，则来自 GraphQL schema 的该类型的所有操作都将可用。

使用示例

查询数据

连接到 Claude Desktop 后，您可以使用如下命令：

View result from countries from graphql (local){}

或者带参数：

View result from country from graphql (local){
  "code": "US"
}

使用 Mutations

对于 mutation，工具以 mutation_ 为前缀，以将其与查询区分开：

View result from mutation_createUser from graphql (local){
  "name": "John Doe",
  "email": "john.doe@example.com"
}

或者更复杂的 mutation：

View result from mutation_updateProduct from graphql (local){
  "id": "prod-123",
  "input": {
    "name": "Updated Product Name",
    "price": 29.99,
    "description": "This is an updated product description"
  }
}

Mutation 遵循与查询相同的模式，但允许您修改 GraphQL API 中的数据。

文档

有关更多详细信息，请参见：

• 入门指南
• 技术文档
• 查询白名单文档
• Mutation 文档
• 项目状态

开发

要更改服务器：

1. 修改 src/graphql-mcp-server.ts 中的 TypeScript 源代码
2. 编译 TypeScript 代码：npm run build
3. 运行编译后的服务器：node dist/graphql-mcp-server.js

发布到 npm

要将此软件包发布到 npm：

# 确保您已登录到 npm
npm login

# 构建项目
npm run build

# 发布到 npm
npm publish

该软件包将包含 dist 目录中预构建的 JavaScript 文件，使其无需额外的构建步骤即可使用。

许可证

本项目采用 Business Source License 1.1 (BSL 1.1) 许可，该许可允许：

• 非商业用途: 您可以将此软件用于任何非商业目的
• 内部商业用途: 您可以将此软件用于不将其作为托管或管理服务提供给第三方的内部商业运营
• 开源转换: 在 2029 年 3 月 14 日，代码将自动转换为 MIT 许可证

商业用途，包括将此软件作为服务提供给他人，需要从 CTK Advisors 获得商业许可证。 有关更多信息，请联系我们或参阅完整的 LICENSE 文件。

BSL 许可证旨在平衡开源可用性与可持续商业开发，在保护我们长期支持和增强软件能力的同时，让每个人都可以免费用于非商业目的。