MCP Graphql

🚀 mcp-graphql

A Model Context Protocol server that enables LLMs to interact with GraphQL APIs. This implementation provides schema introspection and query execution capabilities, allowing models to dynamically discover and use GraphQL APIs.

🚀 Quick Start

Run mcp-graphql and specify the correct endpoint, and it will automatically attempt an introspection query.

Environment Variables (Breaking Change in Version 1.0.0)

⚠️ Important Note

Starting from version 1.0.0, command-line arguments have been replaced with environment variables.

💻 Usage Examples

Basic Usage

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

Using Custom Headers

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

Enabling Mutation Operations

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

Using a Local Schema File Instead of Introspection

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

📚 Documentation

Resources

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

Available Tools

The server provides two main tools:

1. introspect-schema: This tool retrieves the GraphQL schema. If you don't have a schema resource, use this tool first. It uses a local schema file or an introspection query.
2. query-graphql: Execute GraphQL queries against the endpoint. Mutation operations are disabled by default unless ALLOW_MUTATIONS is set to true.

📦 Installation

Install via Smithery

To automatically install the GraphQL MCP server via Smithery for Claude Desktop:

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

Manual Installation

You can manually install it for Claude:

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

🔧 Technical Details

Security Considerations

Mutation operations are disabled by default as a security measure. Please carefully consider enabling mutation operations in a production environment.

Customization for Your Own Server

This is a very generic implementation that allows full introspection and lets users perform any operation (including mutations). If you need a more specific implementation, it is recommended to create your own MCP and restrict clients to call only specific query fields and/or variables. This project can serve as a reference.