GraphQL MCP 服务器

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

特征

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

存储库结构

graphql-mcp/
├── src/
│   └── graphql-mcp-server.ts     # Main server implementation (TypeScript)
├── dist/                         # Compiled JavaScript (generated)
├── docs/
│   ├── GETTING_STARTED.md         # Setup and usage guide
│   ├── PROJECT_STATUS.md          # Current project status
│   └── TECHNICAL.md               # Technical documentation
├── .env.development               # Environment variables
├── .env.sample                    # Sample environment template
├── claude_desktop_sample_config.json  # Sample Claude Desktop config
├── package.json                   # Project dependencies
├── tsconfig.json                  # TypeScript configuration
├── run-graphql-mcp.sh             # Script to run the server
└── README.md                      # This file

先决条件

Node.js 18 或更高版本
TypeScript 5.x 或更高版本
支持 MCP 的 Claude Desktop
GraphQL API 端点（如果未指定，则默认为国家/地区 API）

安装

选项 1：从 npm

# Install globally
npm install -g graphql-mcp

# Run the server
graphql-mcp-server

选项 2：克隆存储库

# Clone the repository
git clone https://github.com/ctkadvisors/graphql-mcp.git
cd graphql-mcp

# Install dependencies
npm install

# Run the server
npm start

快速入门

1.设置环境变量

复制示例环境文件并使用您的 GraphQL API 详细信息进行更新：

cp .env.sample .env.development

使用您的 GraphQL API 端点和可选 API 密钥编辑.env.development 。

2. 构建并运行

首先编译 TypeScript 代码：

npm install
npm run build

然后运行服务器：

node dist/graphql-mcp-server.js

或者使用提供的脚本，一步编译并运行：

./run-graphql-mcp.sh

3. Claude 桌面集成

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

使用示例配置作为模板：
cp claude_desktop_sample_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json
编辑配置并更新路径以指向您的安装：
{ "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\"]" } } } }
重启Claude Desktop以连接到服务器

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

白名单操作

出于安全或性能方面的考虑，你可能需要限制向 Claude 公开的 GraphQL 操作（查询和修改）。控制访问有两种方法：

启用/禁用突变：默认情况下，出于安全考虑，所有突变均处于禁用状态。要启用突变，请执行以下操作：

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

操作白名单：您可以指定哪些特定操作可用：

"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\"]"
  }
}

应避免的常见错误：

// INCORRECT - Will not work!
"WHITELISTED_QUERIES": ["getUser", "getProducts"],
"WHITELISTED_MUTATIONS": ["createOrder", "updateProfile"]

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

如果没有为特定操作类型提供白名单，则 GraphQL 模式中该类型的所有操作都将可用。

示例用法

查询数据

一旦连接到 Claude Desktop，您可以使用以下命令：

View result from countries from graphql (local){}

或者使用参数：

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

使用变异

对于突变，工具以mutation_为前缀，以区别于查询：

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

或者更复杂的突变：

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"
  }
}

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

文档

有关详细信息，请参阅：

发展

要对服务器进行更改：

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

发布到 npm

要将此包发布到 npm：

# Make sure you're logged in to npm
npm login

# Build the project
npm run build

# Publish to npm
npm publish

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

执照

该项目根据商业源许可证 1.1（BSL 1.1）获得许可，该许可证允许：

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

商业使用（包括将此软件作为服务提供给他人）需要获得 CTK Advisors 的商业许可。如需了解更多信息，请联系我们或查看完整的许可文件。

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

GraphQL MCP Server

Integrations