JinDaGe - mcp-graphql MCP Details

article

README

🚀 mcp-graphql

一个模型上下文协议服务器，能让大语言模型（LLM）与GraphQL API进行交互。该实现具备模式内省（introspection）和查询执行功能，可让模型动态发现并使用GraphQL API。

🚀 快速开始

运行mcp-graphql并指定正确的端点，它将自动尝试进行内省（introspect）查询。

✨ 主要特性

支持模式内省和查询执行，方便模型动态发现和使用GraphQL API。
提供了丰富的环境变量配置，可灵活定制服务器行为。
提供两个主要工具，方便检索GraphQL模式和执行查询。

📦 安装指南

通过Smithery安装

要自动通过Smithery安装GraphQL MCP服务器以用于Claude Desktop，可执行以下命令：

npx -y @smithery/cli install mcp-graphql --client claude

手动安装

可以手动安装到Claude，配置如下：

{
    "mcpServers": {
        "mcp-graphql": {
            "command": "npx",
            "args": ["mcp-graphql"],
            "env": {
                "ENDPOINT": "http://localhost:3000/graphql"
            }
        }
    }
}

💻 使用示例

基础用法

# 基本使用，与本地GraphQL服务器通信
ENDPOINT=http://localhost:3000/graphql npx mcp-graphql

高级用法

# 使用自定义头文件
ENDPOINT=https://api.example.com/graphql HEADERS='{"Authorization":"Bearer token123"}' npx mcp-graphql

# 启用变异操作
ENDPOINT=http://localhost:3000/graphql ALLOW_MUTATIONS=true npx mcp-graphql

# 使用本地模式文件而不是内省查询
ENDPOINT=http://localhost:3000/graphql SCHEMA=./schema.graphql npx mcp-graphql

📚 详细文档

环境变量（1.0.0版本的重大变更）

⚠️ 重要提示

从版本1.0.0开始，命令行参数已替换为环境变量。

| 环境变量 | 描述 | 默认值 | |----------|-------------|---------| | ENDPOINT | GraphQL端点URL | http://localhost:4000/graphql | | HEADERS | 请求中的头文件JSON字符串 | {} | | ALLOW_MUTATIONS | 启用变异操作（默认禁用） | false | | NAME | 服务器的名称 | mcp-graphql | | SCHEMA | 本地GraphQL模式文件路径（可选） | - |

资源

graphql-schema：服务器将GraphQL模式作为资源暴露，客户端可以访问。这可以是本地模式文件，也可以基于内省查询。

可用工具

服务器提供两个主要工具：

introspect-schema：此工具用于检索GraphQL模式。如果你没有模式资源，请先使用此工具。它会使用本地模式文件或内省查询。
query-graphql：用于对端点执行GraphQL查询。默认情况下，变异操作是禁用的，除非将ALLOW_MUTATIONS设置为true。

🔧 技术细节

此实现提供模式内省和查询执行功能，允许模型动态发现和使用GraphQL API。运行时指定正确的端点，它将自动尝试内省查询。

📄 许可证

文档未提及相关许可证信息。

🔒 安全注意事项

默认情况下，变异操作是禁用的，这是一种安全措施。请谨慎考虑在生产环境中启用变异操作。

💡 使用建议

这是一个非常通用的实现，允许完整的内省，并且让用户可以执行任何操作（包括变异）。如果你需要更具体的实现，建议创建自己的MCP并限制客户端仅调用特定的查询字段和/或变量。此项目可作为参考。

mcp-graphql