GraphQL MCP

Appearance

GitHubPyPI

Getting Started ​

GraphQL MCP exposes GraphQL APIs as MCP tools for AI agents. Works with any GraphQL library.

Installation ​

bash
pip install graphql-mcp

Or using uv (recommended):

bash
uv add graphql-mcp

Your First MCP Server ​

python
from graphql_api import GraphQLAPI, field
import uvicorn
from graphql_mcp import GraphQLMCP

class HelloAPI:
    @field
    def hello(self, name: str = "World") -> str:
        """Say hello to someone."""
        return f"Hello, {name}!"

api = GraphQLAPI(root_type=HelloAPI)
server = GraphQLMCP.from_api(api, name="Hello")
app = server.http_app()

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8002)

Run it:

bash
python server.py

Your MCP server is running on http://localhost:8002. Visit http://localhost:8002/graphql to test with the built-in MCP Inspector.

What Just Happened? ​

  1. Defined a GraphQL API — @field marks methods as GraphQL query fields
  2. Created MCP Server — GraphQLMCP.from_api() analyzed the schema and generated MCP tools
  3. Started HTTP Server — http_app() creates an ASGI app serving both MCP and GraphQL endpoints

Pick Your Path ​

I have a local GraphQL schema

Use graphql-mcp with Strawberry, Ariadne, Graphene, graphql-api, or any graphql-core schema.

I want to wrap a remote API

Connect to GitHub, Shopify, Hasura, or any existing GraphQL endpoint.

I want to understand the internals

How tool generation works, type mapping, selection sets, nested tools.

I want to customize behavior

mcp_hidden, auth, mutations, middleware, and other configuration.

Troubleshooting ​

Server won't start ​

Make sure all dependencies are installed:

bash
pip install graphql-mcp graphql-api uvicorn

Tools not appearing ​

  • Check that your GraphQL fields have docstrings (these become tool descriptions)
  • Verify mutations are enabled: allow_mutations=True
  • See How It Works for the complete tool generation rules