GraphQL

What is MCP GraphQL?

MCP GraphQL is a Model Context Protocol (MCP) server designed to facilitate interaction with GraphQL APIs. It acts as a bridge, automatically exposing each GraphQL query as a separate MCP tool, enabling MCP-compatible clients to seamlessly communicate with GraphQL services.

How to use MCP GraphQL?

Installation:

• Using uv (recommended): No specific installation is needed; use uvx to directly run mcp-graphql.
• Using pip: pip install mcp-graphql
• From source code: Clone the repository, navigate to the directory, and run pip install .

Usage:

• As a command-line tool:
  • Using uvx: uvx mcp-graphql --api-url="https://api.example.com/graphql" --auth-token="your-token"
  • Using pip installation: mcp-graphql --api-url="https://api.example.com/graphql" --auth-token="your-token"
• As a library: Import serve from mcp_graphql and use asyncio.run(serve(api_url, auth_headers)).

Configuration for Claude.app:

Add mcpServers configuration to your Claude settings, specifying the command and arguments for mcp-graphql using uvx, Docker, or pip installation.

Key Features of MCP GraphQL

• Automatic Tool Exposure: Each GraphQL query is exposed as a distinct MCP tool.
• Dynamic Parameter Matching: Tool parameters automatically match corresponding GraphQL query parameters.
• Automatic JSON Schema Generation: JSON schema for tool inputs is dynamically generated from GraphQL query parameters.
• Schema-less Operation: No schema definition is required; simply provide the API URL and credentials.
• GraphQL Query Support: Currently supports GraphQL queries (mutations planned).
• Configurable Authentication: Supports Bearer, Basic, and custom headers.
• Complex Type Handling: Automatic handling of complex GraphQL types.

Use Cases of MCP GraphQL

• Integrating GraphQL APIs with MCP-compatible clients: Allows applications built on the Model Context Protocol to easily consume and interact with GraphQL services.
• Simplifying GraphQL API consumption: Automates the process of exposing GraphQL queries as usable tools, reducing manual configuration.
• Building AI agents or tools that interact with GraphQL: Enables AI models to understand and utilize GraphQL APIs through the MCP interface.

FAQ about MCP GraphQL

• What are the requirements? Python 3.11 or higher.
• Does it support GraphQL mutations? Not yet, but support for mutations is planned for future releases.
• How does it handle authentication? It supports configurable authentication methods including Bearer, Basic, and custom headers.
• Do I need to define a schema? No, the tool dynamically generates JSON schema from GraphQL query parameters.
• How does it work internally? It introspects the GraphQL API, creates an MCP tool for each query, generates JSON schema for inputs, and handles type conversions. When a tool is called, it converts parameters to a GraphQL query, executes it, and returns results.

MCP GraphQL

An MCP (Model Context Protocol) server that enables interaction with GraphQL APIs.

Description

MCP GraphQL is a tool that implements the Model Context Protocol (MCP) to provide a standardized interface for interacting with GraphQL APIs. It automatically exposes each GraphQL query as a separate MCP tool, allowing MCP-compatible clients to seamlessly communicate with GraphQL services.

Features

• Each GraphQL query is exposed as a distinct MCP tool
• Tool parameters automatically match the corresponding GraphQL query parameters
• JSON schema for tool inputs is dynamically generated from GraphQL query parameters
• No schema definition required - simply provide the API URL and credentials
• Currently supports GraphQL queries (mutations support planned for future releases)
• Configurable authentication (Bearer, Basic, custom headers)
• Automatic handling of complex GraphQL types

Requirements

• Python 3.11 or higher

Installation

Using uv (recommended)

When using uv no specific installation is needed. We will use uvx to directly run mcp-graphql.

Using pip

Alternatively you can install mcp-graphql via pip:

pip install mcp-graphql

Installation from source code

git clone https://github.com/your-username/mcp_graphql.git
cd mcp_graphql
pip install .

Usage

As a command line tool

Using uvx:

uvx mcp-graphql --api-url="https://api.example.com/graphql" --auth-token="your-token"

Using pip installation:

mcp-graphql --api-url="https://api.example.com/graphql" --auth-token="your-token"

or

python -m mcp_graphql --api-url="https://api.example.com/graphql" --auth-token="your-token"

Available options

• --api-url: GraphQL API URL (required)
• --auth-token: Authentication token (optional)
• --auth-type: Authentication type, default is "Bearer" (optional)
• --auth-headers: Custom authentication headers in JSON format (optional)

Example with custom headers:

mcp-graphql --api-url="https://api.example.com/graphql" --auth-headers='{"Authorization": "Bearer token", "X-API-Key": "key"}'

As a library

import asyncio
from mcp_graphql import serve

auth_headers = {"Authorization": "Bearer your-token"}
api_url = "https://api.example.com/graphql"

asyncio.run(serve(api_url, auth_headers))

Configuration

Configure for Claude.app

Add to your Claude settings:

"mcpServers": {
  "graphql": {
    "command": "uvx",
    "args": ["mcp-graphql", "--api-url", "https://api.example.com/graphql"]
  }
}

"mcpServers": {
  "graphql": {
    "command": "docker",
    "args": ["run", "-i", "--rm", "mcp/graphql", "--api-url", "https://api.example.com/graphql"]
  }
}

"mcpServers": {
  "graphql": {
    "command": "python",
    "args": ["-m", "mcp_graphql", "--api-url", "https://api.example.com/graphql"]
  }
}

How It Works

MCP GraphQL automatically:

1. Introspects the provided GraphQL API
2. Creates an MCP tool for each available GraphQL query
3. Generates JSON schema for tool inputs based on query parameters
4. Handles type conversions between GraphQL and JSON

When a tool is called, the server:

1. Converts the tool call parameters to a GraphQL query
2. Executes the query against the API
3. Returns the results to the MCP client

Planned Features

• Support for GraphQL mutations (with appropriate safeguards)
• Improved error handling and validation
• Additional optimizations based on specific GraphQL API implementations

Development

Setting up the development environment

# Create virtual environment using uv
uv venv

# Install dependencies
uv sync

Linting

ruff check .

License

This project is licensed under the MIT License. See the LICENSE file for details.

Contributing

Contributions are welcome. Please feel free to submit a Pull Request or open an Issue.