mcp-graphql

mcp-graphql

一个 Model Context Protocol 服务，可让大模型与 GraphQL API 交互。此实现提供架构内省和查询执行功能，使模型能够动态发现和使用 GraphQL API。

用法

使用正确的端点运行 mcp-graphql，它会自动尝试内省你的查询。

环境变量（1.0.0 中的重大变更）

注意： 从 1.0.0 版本起，命令行参数已替换为环境变量。

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

示例

# Basic usage with a local GraphQL server
ENDPOINT=http://localhost:3000/graphql npx mcp-graphql

# Using with custom headers
ENDPOINT=https://api.example.com/graphql HEADERS='{"Authorization":"Bearer token123"}' npx mcp-graphql

# Enable mutation operations
ENDPOINT=http://localhost:3000/graphql ALLOW_MUTATIONS=true npx mcp-graphql

# Using a local schema file instead of introspection
ENDPOINT=http://localhost:3000/graphql SCHEMA=./schema.graphql npx mcp-graphql

# Using a schema file hosted at a URL
ENDPOINT=http://localhost:3000/graphql SCHEMA=https://example.com/schema.graphql npx mcp-graphql

资源

• graphql-schema：服务将 GraphQL 架构作为资源公开，客户端可以访问。该资源可以是本地架构文件、托管在 URL 上的架构文件，也可以基于内省查询生成。

可用工具

服务提供两个主要工具：

1. introspect-schema：此工具用于获取 GraphQL 架构。如果你无法通过资源访问架构，请先使用此工具。 此工具使用本地架构文件、托管在 URL 上的架构文件，或内省查询。

2. query-graphql：对端点执行 GraphQL 查询。默认情况下，除非将 ALLOW_MUTATIONS 设为 true，否则会禁用变更操作。

安装

通过 Smithery 安装

要通过 Smithery 为 Claude Desktop 自动安装 GraphQL MCP Server：

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

手动安装

可以手动安装到 Claude：

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

安全注意事项

默认禁用变更操作，以防止大模型修改你的数据库或服务数据。请谨慎考虑是否在生产环境中启用变更操作。

为你自己的服务进行自定义

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