mcp-graphql-enhanced
mcp-graphql-enhanced
一个用于 GraphQL 的增强型 MCP(模型上下文协议)服务器,解决了 LLM 与 GraphQL API 之间实际应用中的互操作性问题。
mcp-graphql的直接替代品——具有动态标头、强大的变量解析功能,且零破坏性变更。
💬 社区与支持
加入讨论!如果您对将此桥接器与 Neo4j、Discord 数据图或一般的 GraphQL 一起使用有疑问,欢迎加入我们:
Discord 频道: #mcp-graphql-enhanced
服务器: 官方 GraphQL Discord
这是分享反馈、报告问题或建议桥接器新“增强”功能的最佳场所。
Related MCP server: mcp-graphql-schema
✨ 关键增强功能
✅ 内置 GraphiQL IDE — 位于 http://localhost:MCP_PORT/(或 /graphiql)的可视化操练场,带有预配置的标头。
✅ 双重传输 — 同时支持 STDIO(用于本地 CLI/客户端工具)和 HTTP/JSON-RPC(用于外部/浏览器客户端)。
✅ 动态标头 — 通过工具参数传递
Authorization、X-API-Key等(无需重启配置)。✅ 强大的变量解析 — 修复了
“Query variables must be a null or an object”错误。✅ 过滤后的内省 — 仅请求特定类型(例如
typeNames: ["Query", "User"])以减少 LLM 上下文噪声。✅ 完全兼容 MCP — 可与 Claude Desktop、Cursor、Glama 配合使用。
✅ 默认安全 — 除非明确启用,否则禁用变更(mutations)。
✅ 动态模式演进 — 为即时重新生成 GraphQL 类型(如 Neo4j)的服务器提供智能诊断和差距分析。
✅ 深度可观测性 — 自动从 GraphQL 扩展中提取并清理 Cypher。
🚀 多端点广播(v3.9.0+ 实验性功能)
从 v3.9.0 开始,服务器支持同时查询多个 GraphQL 端点。此功能最初旨在同步不同环境(例如 Node.js 和 Python 后端)之间的变更,但它为数据聚合开启了强大的可能性。
零破坏性变更:如果您在
ENDPOINT中提供单个 URL,服务器的行为与之前完全相同。智能聚合:当提供多个以逗号分隔的 URL 时,服务器会将查询广播到所有端点并合并结果数组。
绕过免费层限制:非常适合“免费层”云数据库(如 Neo4j Aura)的用户。您可以将数据拆分到多个免费实例中,并使用此桥接器将它们作为单个统一图谱进行查询,从而有效绕过实体数量限制。
去重:桥接器会自动根据唯一字段删除重复对象,以保持 AI 上下文窗口的整洁。
⚠️ 使用风险自负: 此功能假设所有端点共享相同(或非常相似)的 GraphQL 模式。内省是针对列表中的第一个端点执行的。
💡 用例:桥接 WSL 和 Windows (PowerShell)
Windows 开发人员面临的一个常见挑战是 Windows Linux 子系统 (WSL) 与宿主操作系统之间的网络隔离。此功能允许您将这两个世界桥接成一个“统一神经系统”。
Claude Desktop 的配置示例:
{
"ENDPOINT": "http://DESKTOP-NAME.local:2311/graphql,http://127.0.0.1:4000/graphql"
}混合生态系统:无缝查询并聚合 Windows 原生进程 (PowerShell) 和基于 Linux 的环境 (WSL) 之间的数据。
mDNS 支持:通过使用 .local 地址,桥接器会自动从 WSL 环境内解析宿主机的 IP。
透明聚合:AI 助手与单个统一模式交互,而无需感知数据是同时从不同操作系统获取的。
🔍 高级可观测性与 Cypher
该桥接器提供了关于 LLM 如何与您的图数据库交互的深度见解。
🕸️ 自动 Cypher 提取
对于返回查询执行计划的 GraphQL 服务器实现(如 @neo4j/graphql),桥接器会自动:
检测响应中的
extensions.cypher。清理输出,剥离内部标头(如
CYPHER 5或空的PARAMS)。注入一个干净的 Cypher 块直接到工具的输出中,供 AI 分析。
注意: 此功能要求您的 GraphQL 服务器配置为在响应扩展中包含调试信息。
🎨 可视化控制中心 (GraphiQL)
与标准 MCP 服务器不同,此服务器为人类提供了可视化界面。当使用 ENABLE_HTTP=true 运行时,您可以在浏览器中打开功能齐全的 GraphiQL IDE。
端点:
http://localhost:6274/(或/graphiql)标头同步: 环境中设置的任何标头(如 GitHub 令牌)都会自动注入到 GraphiQL 的“Headers”选项卡中,以便立即测试。
💻 HTTP / 双重传输
此服务器现在以双重传输模式运行,同时支持标准 STDIO 通信(大多数 MCP 客户端使用)和端口 6274 上的新 HTTP JSON-RPC 端点。
这允许外部系统、Web 应用程序和直接的 curl 命令访问服务器工具,并在您的终端中提供实时请求日志([HTTP-RPC] 日志)。
端点 | 方法 | 描述 |
|
| 人机界面:可视化的 GraphQL IDE。 |
|
| 用于工具执行的主要 JSON-RPC 2.0 端点。 |
|
| 简单的健康检查,返回 |
自动端口选择
服务器默认使用端口 6274。如果您遇到 EADDRINUSE 错误,服务器将自动查找下一个可用端口。请查看服务器日志以获取最终绑定的端口(例如 [HTTP] Started server on http://localhost:6275)。
解决端口冲突 (EADDRINUSE) 和自动端口选择
服务器默认使用端口 6274。如果您遇到 EADDRINUSE: address already in use :::6274 错误(由于僵尸进程,在本地开发中很常见),服务器将自动查找下一个可用端口(最多尝试 10 次,不会生成多个服务器)。
这确保了即使默认端口被占用,服务器也能成功启动。如果您的 curl 或客户端工具在默认的 6274 上失败,请务必查看服务器日志以获取最终绑定的端口(例如 [HTTP] Started server on http://localhost:6275)。
要强制使用特定端口(例如,为了保证外部防火墙设置),您仍然可以显式设置 MCP_PORT 环境变量:
测试 HTTP 端点
只要服务器正在运行(例如通过 npm run dev),您就可以使用 curl 测试端点:
# Test the health check (assuming the server bound to the default or found the next available port)
curl http://localhost:6274/health
# Example: Test the query tool via JSON-RPC (using port 6275 if 6274 was busy)
curl -X POST http://localhost:6275/mcp -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"query-graphql","params":{"query":"query { __typename }"},"id":1}'
## 🔍 Filtered Introspection
Avoid 50k-line schema dumps. Ask for only what you need:
`@introspect-schema typeNames ["Query", "User"]`
## 🔍 Debug & Inspect
Use the official MCP Inspector to test your server live:
```bash
npx @modelcontextprotocol/inspector \
-e ENDPOINT=https://api.example.com/graphql \
npx @letoribo/mcp-graphql-enhanced环境变量(1.0.0 版本中的破坏性变更)
注意: 从 1.0.0 版本开始,命令行参数已被环境变量取代。
环境变量 | 描述 | 默认值 |
| GraphQL 端点 URL |
|
| 包含请求标头的 JSON 字符串 |
|
| 启用变更操作(默认禁用) |
|
| MCP 服务器名称 |
|
| 本地 GraphQL 模式文件路径或 URL | - |
| HTTP/JSON-RPC 服务器端口。 |
|
| 启用 HTTP 传输: |
|
| 设置为 | - |
关于 |
auto(默认):仅在 MCP Inspector 中运行时自动启用 HTTP...true:始终启用 HTTP 服务器false:完全禁用 HTTP 服务器
示例
# Basic usage
ENDPOINT=http://localhost:3000/graphql npx @letoribo/mcp-graphql-enhanced
# With auth header
ENDPOINT=https://api.example.com/graphql \
HEADERS='{"Authorization":"Bearer xyz"}' \
npx @letoribo/mcp-graphql-enhanced
# Enable mutations
ENDPOINT=http://localhost:3000/graphql \
ALLOW_MUTATIONS=true \
npx @letoribo/mcp-graphql-enhanced
# Use local schema file
ENDPOINT=http://localhost:3000/graphql \
SCHEMA=./schema.graphql \
npx @letoribo/mcp-graphql-enhanced
# Change the HTTP port
MCP_PORT=8080 npx @letoribo/mcp-graphql-enhanced
# Disable HTTP transport (fastest, recommended for Claude Desktop)
ENABLE_HTTP=false npx @letoribo/mcp-graphql-enhanced
# Test the surgical precision and the IDE immediately:
ENDPOINT=https://api.github.com/graphql \
HEADERS='{"Authorization":"Bearer YOUR_GITHUB_TOKEN"}' \
ENABLE_HTTP=true \
npx @letoribo/mcp-graphql-enhanced
# Then visit http://localhost:6274/graphiql🖥️ Claude Desktop 配置示例
您可以使用 npx 包(为简单起见推荐)或 Docker 镜像(适合可重复性和隔离性)将 Claude Desktop 连接到您的 GraphQL API。
✅ 选项 1:使用 npx
{
"mcpServers": {
"mcp-graphql-enhanced": {
"command": "npx",
"args": ["@letoribo/mcp-graphql-enhanced"],
"env": {
"ENDPOINT": "https://your-api.com/graphql"
}
}
}
}🐳 选项 2:使用 Docker(支持自动拉取)
{
"mcpServers": {
"mcp-graphql-enhanced": {
"command": "sh",
"args": [
"-c",
"docker run --rm -i -e ENDPOINT=$ENDPOINT -e HEADERS=$HEADERS -e ALLOW_MUTATIONS=$ALLOW_MUTATIONS ghcr.io/letoribo/mcp-graphql-enhanced:main"
],
"env": {
"ENDPOINT": "https://your-api.com/graphql",
"HEADERS": "{\"Authorization\": \"Bearer YOUR_TOKEN\"}",
"ALLOW_MUTATIONS": "false"
}
}
}
}🧪 选项 3:使用 node 和本地构建(用于开发)
如果您克隆了仓库并构建了项目(npm run build → 输出到 dist/):
{
"mcpServers": {
"mcp-graphql-enhanced": {
"command": "node",
"args": ["dist/index.js"],
"env": {
"ENDPOINT": "https://your-api.com/graphql",
"ALLOW_MUTATIONS": "true"
}
}
}
}资源
graphql-schema:服务器将 GraphQL 模式作为客户端可以访问的资源公开。这可以是本地模式文件、托管在 URL 上的模式文件,或者是基于内省查询的结果。
可用工具
服务器提供两个主要工具:
introspect-schema:此工具检索 GraphQL 模式或过滤后的子集(通过 typeNames)。如果您无法将模式作为资源访问,请先使用此工具。 它使用本地模式文件、托管在 URL 上的模式文件或内省查询。 过滤后的内省 (typeNames) 仅在使用实时 GraphQL 端点时可用(不适用于 SCHEMA 文件或 URL)。
query-graphql:针对端点执行 GraphQL 查询。默认情况下,除非将
ALLOW_MUTATIONS设置为true,否则禁用变更。
安全注意事项
默认情况下禁用变更以防止意外的数据更改。请务必在生产环境中验证 HEADERS 和 SCHEMA 输入。尽可能使用 HTTPS 端点和短效令牌。
为您自己的服务器进行自定义
这是一个非常通用的实现,它允许完全内省,并允许您的用户执行任何操作(包括变更)。如果您需要更具体的实现,我建议您创建自己的 MCP,并锁定工具调用,以便客户端只能输入特定的查询字段和/或变量。您可以将其作为参考。
Available Tools
2 toolsintrospect-schemaA
Retrieve GraphQL schema details or system manifest. READ-ONLY: Non-destructive metadata discovery. Usage: 1. If 'typeNames' is provided: Returns the full SDL (Schema Definition Language) for the requested types, including fields and relations. 2. If 'typeNames' is omitted: Returns a Federated Manifest—a high-level summary of connected nodes, their capabilities, and available domain entities (not the full schema). Use this to navigate the federated graph topology before executing queries.
| Name | Required | Description | Default |
|---|---|---|---|
| headers | No | JSON stringified object of extra HTTP headers for the introspection request (e.g. '{"Authorization": "Bearer token"}'). | |
| endpoint | No | Optional target GraphQL HTTP/HTTPS URL to dynamically switch endpoint before execution. | |
| typeDepth | No | Depth of nested fields to retrieve (default: 2) | |
| typeNames | No | List of specific GraphQL type names to introspect. If provided, returns the detailed SDL definitions for these types. If omitted, returns a system-wide Federated Manifest overview. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it explicitly declares 'READ-ONLY: Non-destructive metadata discovery.' It also discloses the two distinct behavioral outcomes based on typeNames and clarifies that the manifest is 'not the full schema,' which helps set expectations. It does not mention potential errors or how headers/endpoint affect behavior, but the core safety and conditional behavior are clearly communicated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear one-line summary, an explicit READ-ONLY safety cue, and a numbered list that front-loads the two usage modes. Every sentence contributes either to behavioral transparency or invocation guidance, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a moderate-complexity tool with zero required parameters and no output schema, the description is largely complete: it covers both invocation modes, the manifest vs. SDL distinction, and the read-only nature. It could be more complete by explicitly routing query execution to query-graphql, but this is a minor gap given the clear 'before executing queries' framing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3, but the description adds meaningful behavior beyond the schema by explaining the conditional outcome for typeNames and clarifying that results include 'fields and relations.' This gives an agent a better mental model of what each parameter triggers, even though the schema already documents the parameters themselves.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as retrieving GraphQL schema details or a system manifest, with a specific verb and resource. It distinguishes between two modes—full SDL for requested types versus a Federated Manifest overview—and positions it as metadata discovery before executing queries, differentiating it from the sibling query-graphql tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit conditional guidance: use typeNames to get full SDL definitions, omit it to get a manifest for navigating the federated graph. It also states to use the manifest 'before executing queries,' providing clear context. However, it does not explicitly name or exclude the sibling tool query-graphql as the alternative for actual query execution.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
query-graphqlA
Execute GraphQL operations (queries and mutations) against the federated system. WARNING: This tool performs remote operations. 'Mutation' operations will modify persistent state; execute these only when a state change is intended. Prerequisites: Verify schema structure using 'introspect-schema' before executing complex queries. Security: Inherits environment-based authentication. Returns: A JSON object containing the execution result ('data') or a list of 'errors' in case of failure.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The GraphQL query or mutation string. Example: 'query { guilds { id name } }'. | |
| headers | No | JSON stringified object of extra HTTP headers for the request. | |
| endpoint | No | Optional target GraphQL HTTP/HTTPS URL to dynamically switch endpoint before execution. | |
| variables | No | JSON stringified object of variables. Example: '{"id": "123"}'. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does so well: it discloses that the tool performs remote operations, that mutations modify persistent state, that authentication is inherited from the environment, and that failures return an errors list. These are the key behavioral facts an agent needs beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into clear warning, prerequisite, security, and return-value statements with no filler. It is slightly longer than a minimal two-sentence description, but each section contributes a distinct piece of operational knowledge.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given four parameters and no output schema or annotations, the description covers the essential operating context: when to verify schema, mutation risk, authentication model, and expected return structure. No critical information needed to call the tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description adds value by warning that the required query string may contain operations that mutate persistent state, and by noting the return shape. It does not repeat schema descriptions, but provides meaningful semantic context for the query parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action verb ('Execute') and target ('GraphQL operations ... against the federated system'), distinguishing this as the operation-execution tool while the sibling 'introspect-schema' is referenced only for schema verification. The clarification that it handles both queries and mutations further disambiguates its role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly names the sibling tool as a prerequisite step ('Verify schema structure using introspect-schema before executing complex queries'), and warns to execute mutations only when a state change is intended. This gives the agent clear when-to-use and when-not-to-use guidance for mutation operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
2 tool updates
v4.15.2- Changed
introspect-schema2 fields changed- added
Input schema / properties / endpointAdded value: +{ + "description": "Optional target GraphQL HTTP/HTTPS URL to dynamically switch endpoint before execution.", + "type": "string" +} - added
Input schema / properties / headersAdded value: +{ + "description": "JSON stringified object of extra HTTP headers for the introspection request (e.g. '{\"Authorization\": \"Bearer token\"}').", + "type": "string" +}
- Changed
query-graphql1 field changed- added
Input schema / properties / endpointAdded value: +{ + "description": "Optional target GraphQL HTTP/HTTPS URL to dynamically switch endpoint before execution.", + "type": "string" +}
1 tool update
v4.13.1- Added
introspect-schema
1 tool update
v4.12.0- Removed
introspect-schema
1 tool update
v4.9.2- Changed
introspect-schema1 field changed- removed
Input schema / properties / typeDepth / defaultRemoved value: -2
2 tool updates
v4.8.0- Changed
introspect-schema2 fields changed- added
Input schema / properties / typeDepthAdded value: +{ + "default": 2, + "description": "Depth of nested fields to retrieve (default: 2)", + "type": "number" +} - changed
Input schema / properties / typeNames / descriptionPrevious value: -"List of specific GraphQL type names to introspect. If omitted, the full schema is returned (use with caution on large APIs)."New value: +"List of specific GraphQL type names to introspect. If provided, returns the detailed SDL definitions for these types. If omitted, returns a system-wide Federated Manifest overview."
- Changed
query-graphql3 fields changed- changed
Input schema / properties / headers / descriptionPrevious value: -"JSON string of extra HTTP headers for the request."New value: +"JSON stringified object of extra HTTP headers for the request." - changed
Input schema / properties / query / descriptionPrevious value: -"The GraphQL query or mutation string."New value: +"The GraphQL query or mutation string. Example: 'query { guilds { id name } }'." - changed
Input schema / properties / variables / descriptionPrevious value: -"JSON string of variables for the operation."New value: +"JSON stringified object of variables. Example: '{\"id\": \"123\"}'."
2 tool updates
v4.2.0- Changed
introspect-schema1 field changed- changed
Input schema / properties / typeNames / descriptionPrevious value: -"List of type names to introspect"New value: +"List of specific GraphQL type names to introspect. If omitted, the full schema is returned (use with caution on large APIs)."
- Changed
query-graphql3 fields changed- changed
Input schema / properties / headers / descriptionPrevious value: -"JSON string of extra headers"New value: +"JSON string of extra HTTP headers for the request." - changed
Input schema / properties / query / descriptionPrevious value: -"The GraphQL query or mutation string"New value: +"The GraphQL query or mutation string." - changed
Input schema / properties / variables / descriptionPrevious value: -"JSON string of variables"New value: +"JSON string of variables for the operation."
2 tool updates
v3.9.3- Added
introspect-schema - Added
query-graphql
2 tool updates
v2.0.7- Removed
introspect-schema - Removed
query-graphql
2 tool updates
v1.0.0- Changed
introspect-schema3 fields changed- added
Input schema / $schemaAdded value: +"http://json-schema.org/draft-07/schema#" - added
Input schema / additionalPropertiesAdded value: +false - changed
Input schema / properties / typeNames / descriptionPrevious value: -"e.g., [\"Query\", \"User\"]"New value: +"A list of specific type names to filter the introspection."
- Changed
query-graphql2 fields changed- added
Input schema / $schemaAdded value: +"http://json-schema.org/draft-07/schema#" - added
Input schema / additionalPropertiesAdded value: +false
TDQS
Scored across 2 tools
query-graphql handles all execution, including state-changing mutations, while introspect-schema is strictly read-only metadata discovery. Their purposes are sharply separated with no overlap.
Both tools follow the same verb-noun hyphenated pattern: query-graphql and introspect-schema. The naming is predictable and consistent.
Two tools is slightly below the typical 3-15 range, but it is a reasonable and well-scoped count for a GraphQL server: one execution tool and one schema-discovery tool. Each tool earns its place.
For a GraphQL-focused server, the pair covers the full interaction surface: schema/introspection discovery and arbitrary query/mutation execution. There are no obvious missing capabilities.
Maintenance
Related MCP Connectors
The official MCP Server for the Mux API
MCP server for the Seline Analytics API
The official MCP Server from Mia-Platform to interact with Mia-Platform Console
An MCP server that let you interact with Cycloid.io Internal Development Portal and Platform
Related MCP Servers
- MIT
- AlicenseNot gradedqualityDmaintenanceA MCP server that exposes GraphQL schema information to LLMs like Claude. This server allows an LLM to explore and understand large GraphQL schemas through a set of specialized tools, without needing to load the whole schema into the context35 npm46MIT
- AlicenseAqualityDmaintenanceGraphQL MCP Server that acts as a bridge allowing MCP clients (like Cursor or Claude Desktop) to interact with target GraphQL APIs through standard tools for schema introspection and operation execution.213 npm3MIT
- AlicenseNot gradedqualityDmaintenanceMCP that can proxy any GraphQL API and expose graphql operations as mcp tools.13 npm18Apache 2.0