mcp-graphql-enhanced

An enhanced MCP (Model Context Protocol) server for GraphQL that fixes real-world interoperability issues between LLMs and GraphQL APIs.

Drop-in replacement for mcp-graphql — with dynamic headers, robust variables parsing, and zero breaking changes.

✨ Key Enhancements

• ✅ Dynamic headers — pass Authorization, X-API-Key, etc., via tool arguments (no config restarts)

• ✅ Robust variables parsing — fixes “Query variables must be a null or an object” error

• ✅ Filtered introspection — request only specific types (e.g., typeNames: ["Query", "User"]) to reduce LLM context noise

• ✅ Full MCP compatibility — works with Claude Desktop, Cursor, Glama

• ✅ Secure by default — mutations disabled unless explicitly enabled

🔍 Filtered Introspection (New!)

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:

Environment Variables (Breaking change in 1.0.0)

Note: As of version 1.0.0, command line arguments have been replaced with environment variables.

Examples

🖥️ Claude Desktop Configuration Examples

You can connect Claude Desktop to your GraphQL API using either the npx package (recommended for simplicity) or the Docker image (ideal for reproducibility and isolation).

✅ Option 1: Using npx

🐳 Option 2: Using Docker (auto-pull supported)

🧪 Option 3: Using node with local build (for development)

If you’ve cloned the repo and built the project (npm run build → outputs to dist/):

Resources

• graphql-schema: The server exposes the GraphQL schema as a resource that clients can access. This is either the local schema file, a schema file hosted at a URL, or based on an introspection query.

Available Tools

The server provides two main tools:

1. introspect-schema: This tool retrieves the GraphQL schema or a filtered subset (via typeNames). Use this first if you don't have access to the schema as a resource. This uses either the local schema file, a schema file hosted at a URL, or an introspection query. Filtered introspection (typeNames) is only available when using a live GraphQL endpoint (not with SCHEMA file or URL).

2. query-graphql: Execute GraphQL queries against the endpoint. By default, mutations are disabled unless ALLOW_MUTATIONS is set to true.

Security Considerations

Mutations are disabled by default to prevent unintended data changes. Always validate HEADERS and SCHEMA inputs in production. Use HTTPS endpoints and short-lived tokens where possible.

Customize for your own server

This is a very generic implementation where it allows for complete introspection and for your users to do whatever (including mutations). If you need a more specific implementation I'd suggest to just create your own MCP and lock down tool calling for clients to only input specific query fields and/or variables. You can use this as a reference.