mcp-graphql-schema

This MCP server exposes the GraphQL schema information of a provided GraphQL SDL file to LLMs via a set of specialized tools. It lets you inspect root query, mutation, and subscription fields, view detailed type definitions, search for types and fields by name patterns, and obtain simplified field information including argument types. Internal GraphQL types are filtered out for clearer results, making it easier for models to navigate complex schemas. To use it, run the server with a target schema file (either a default file like schema.graphqls in the current directory or a specific path) and then invoke the available MCP tools such as list-query-fields, get-type, or search-schema to explore the schema. The server is designed to integrate with Claude Desk or Claude Code, enabling you to ask questions about the schema and receive structured SDL or descriptive outputs.

Prerequisites:

• Node.js installed (which provides npm/npmx).
• Access to npx (comes with npm).

Installation steps:

1. Ensure you have Node.js and npm installed. You can verify: node -v npm -v

2. Install and run the MCP server using npx with the GraphQL schema package:

   • You can use a default schema file by placing schema.graphqls in your current directory or pass a path to your SDL file.

3. Example command to run the server against a specific schema: npx -y mcp-graphql-schema /path/to/your/schema.graphqls

4. (Optional) If you want to install via Smithery for Claude Desktop integration: npx -y @smithery/cli install @hannesj/mcp-graphql-schema --client claude

5. If you are configuring Claude Desktop, you can add the server to claude_desktop_config.json as shown in the README (adjust the absolute path to your schema): { "mcpServers": { "GraphQL Schema": { "command": "npx", "args": ["-y", "mcp-graphql-schema", "/ABSOLUTE/PATH/TO/schema.graphqls"] } } }

Tips and considerations:

• Use a definitive absolute path to your schema file when configuring Claude Desktop or Claude Code to avoid path resolution issues.
• The MCP tools include: list-query-fields, get-query-field, list-mutation-fields, get-mutation-field, list-subscription-fields, get-subscription-field, list-types, get-type, get-type-fields, and search-schema. Use these to iteratively explore the schema.
• You can run multiple MCP servers for different schemas by giving each a distinct name, e.g., GraphQL Schema and Shopify GraphQL Schema.
• If you encounter permissions or network issues when using npx, ensure npm is up to date and you have network access. For local development, you can also consider installing the package locally and running it via node if a local start script is provided by the package.
• When using Claude integration, you can leverage the -s/--scope option to choose where configuration is stored (project vs global).