GraphQL Schema

What is mcp-graphql-schema?

mcp-graphql-schema is a Model Context Protocol (MCP) server designed to expose GraphQL schema information to Large Language Models (LLMs) like Claude. It allows LLMs to explore and understand complex GraphQL schemas without overwhelming their context window, by providing a set of specialized tools to interact with the schema.

How to use mcp-graphql-schema?

Command Line

Run the MCP server with a specific schema file:

npx -y mcp-graphql-schema # Use default schema.graphqls
npx -y mcp-graphql-schema ../schema.shopify.2025-01.graphqls # Use a specific relative path schema
npx -y mcp-graphql-schema /absolute/path/to/schema.graphqls # Use a specific absolute path schema
npx -y mcp-graphql-schema --help # Show help

Installing via Smithery

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

Claude Desktop Integration

Edit your claude_desktop_config.json:

{
  "mcpServers": {
    "GraphQL Schema": {
      "command": "npx",
      "args": ["-y", "mcp-graphql-schema", "/ABSOLUTE/PATH/TO/schema.graphqls"]
    }
  }
}

Claude Code Integration

1. Add the GraphQL Schema MCP server to Claude Code:

   claude mcp add graphql-schema npx -y mcp-graphql-schema
   claude mcp add shopify-graphql-schema npx -y mcp-graphql-schema  ~/Projects/work/schema.shopify.2025-01.graphqls
   

2. Verify the MCP server is registered:

   claude mcp list
   claude mcp get graphql-schema
   

3. Remove the server if needed:

   claude mcp remove graphql-schema
   

4. Use the tool in Claude Code by asking questions about the GraphQL schema.

Key Features of mcp-graphql-schema

• Load any GraphQL schema file via command line argument.
• Explore query, mutation, and subscription fields.
• Look up detailed type definitions.
• Search for types and fields using pattern matching.
• Get simplified field information including types and arguments.
• Filter out internal GraphQL types for cleaner results.
• Provides various MCP tools for LLMs: 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, search-schema.

Use Cases of mcp-graphql-schema

• LLM-powered GraphQL schema exploration: Allows LLMs to understand and interact with large GraphQL schemas without being overwhelmed by context.
• Automated documentation generation: LLMs can use the provided tools to extract and summarize schema information.
• Intelligent API interaction: LLMs can generate correct GraphQL queries and mutations based on their understanding of the schema.
• Developer productivity: Developers can leverage LLMs to quickly understand unfamiliar GraphQL APIs.

FAQ about mcp-graphql-schema

Q: What is the purpose of mcp-graphql-schema? A: It acts as a bridge, allowing Large Language Models (LLMs) to effectively understand and navigate complex GraphQL schemas by providing a structured way to query schema information.

Q: How does it prevent context bloating for LLMs? A: Instead of feeding the entire schema to the LLM, it provides specific tools that the LLM can use to request only the relevant parts of the schema as needed, thus managing the context efficiently.

Q: Can I use it with any GraphQL schema? A: Yes, you can load any GraphQL schema file by specifying its path when running the server.

Q: What kind of information can LLMs retrieve about the schema? A: LLMs can retrieve information about query, mutation, and subscription fields, detailed type definitions, simplified field information, and can search for types and fields using pattern matching.

Q: Is it compatible with different Claude environments? A: Yes, it provides integration instructions for Claude Desktop and Claude Code CLI, making it versatile for different Claude users.

GraphQL Schema Model Context Protocol Server

A Model Context Protocol (MCP) server that exposes GraphQL schema information to Large Language Models (LLMs) like Claude. This server allows an LLM to explore and understand GraphQL schemas through a set of specialized tools.

Features

• Load any GraphQL schema file specified via command line argument
• Explore query, mutation, and subscription fields
• Look up detailed type definitions
• Search for types and fields using pattern matching
• Get simplified field information including types and arguments
• Filter out internal GraphQL types for cleaner results

Usage

Command Line

Run the MCP server with a specific schema file:

# Use the default schema.graphqls in current directory
npx -y mcp-graphql-schema

# Use a specific schema file (relative path)
npx -y mcp-graphql-schema ../schema.shopify.2025-01.graphqls

# Use a specific schema file (absolute path)
npx -y mcp-graphql-schema /absolute/path/to/schema.graphqls

# Show help
npx -y mcp-graphql-schema --help

Installing via Smithery

To install GraphQL Schema for Claude Desktop automatically via Smithery:

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

Claude Desktop Integration

To use this MCP server with Claude Desktop, edit your claude_desktop_config.json configuration file:

{
  "mcpServers": {
    "GraphQL Schema": {
      "command": "npx",
      "args": ["-y", "mcp-graphql-schema", "/ABSOLUTE/PATH/TO/schema.graphqls"]
    }
  }
}

Location of the configuration file:

• macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: $env:AppData\Claude\claude_desktop_config.json

Claude Code Integration

To use this MCP server with Claude Code CLI, follow these steps:

1. Add the GraphQL Schema MCP server to Claude Code

   # Basic syntax
   claude mcp add graphql-schema npx -y mcp-graphql-schema
   
   # Example with specific schema
   claude mcp add shopify-graphql-schema npx -y mcp-graphql-schema  ~/Projects/work/schema.shopify.2025-01.graphqls
   

2. Verify the MCP server is registered

   # List all configured servers
   claude mcp list
   
   # Get details for your GraphQL schema server
   claude mcp get graphql-schema
   

3. Remove the server if needed

   claude mcp remove graphql-schema
   

4. Use the tool in Claude Code

   Once configured, you can invoke the tool in your Claude Code session by asking questions about the GraphQL schema.

Tips:

• Use the -s or --scope flag with project (default) or global to specify where the configuration is stored
• Add multiple MCP servers for different schemas with different names (e.g., main API schema, Shopify schema)

MCP Tools

The server provides the following tools for LLMs to interact with GraphQL schemas:

• list-query-fields: Lists all available root-level fields for GraphQL queries
• get-query-field: Gets detailed definition for a specific query field in SDL format
• list-mutation-fields: Lists all available root-level fields for GraphQL mutations
• get-mutation-field: Gets detailed definition for a specific mutation field in SDL format
• list-subscription-fields: Lists all available root-level fields for GraphQL subscriptions (if present in schema)
• get-subscription-field: Gets detailed definition for a specific subscription field (if present in schema)
• list-types: Lists all types defined in the GraphQL schema (excluding internal types)
• get-type: Gets detailed definition for a specific GraphQL type in SDL format
• get-type-fields: Gets a simplified list of fields with their types for a specific GraphQL object type
• search-schema: Searches for types or fields in the schema by name pattern (case-insensitive regex)

Examples

Example queries to try:

What query fields are available in this GraphQL schema?
Show me the details of the "user" query field.
What mutation operations can I perform in this schema?
List all types defined in this schema.
Show me the definition of the "Product" type.
List all fields of the "Order" type.
Search for types and fields related to "customer".