GraphQL-MCP
A library for automatically generating FastMCP tools from GraphQL APIs using graphql-api.
This allows you to expose your GraphQL API as MCP tools that can be used by AI agents and other systems.
Quick Start
Install graphql-mcp with graphql-api:
pip install graphql-mcp graphql-api
Create a simple GraphQL API and expose it as MCP tools:
import asyncio
import uvicorn
from graphql_api import GraphQLAPI, field
from graphql_mcp.server import GraphQLMCP
class HelloWorldAPI:
@field
def hello(self, name: str = "World") -> str:
return f"Hello, {name}!"
api = GraphQLAPI(root_type=HelloWorldAPI)
server = GraphQLMCP.from_api(api)
mcp_app = server.http_app(
transport="streamable-http",
stateless_http=True
)
if __name__ == "__main__":
uvicorn.run(mcp_app, host="0.0.0.0", port=8002)
That's it! Your GraphQL API is now available as MCP tools.
Features
- Automatic Tool Generation: Converts GraphQL queries and mutations into MCP tools
- Type-Safe: Maps GraphQL types to Python types with full type hints
- Built-in HTTP Server: Serves both MCP and GraphQL endpoints
- Authentication: Supports JWT and bearer token authentication
- Remote GraphQL: Connect to existing GraphQL APIs
- Production Ready: Built on FastMCP and Starlette
- Built-in MCP Inspector: Web-based GraphiQL interface for testing and debugging
Usage with graphql-api
The recommended way to use GraphQL MCP is with the graphql-api library, which provides a simple, decorator-based approach to building GraphQL APIs:
from graphql_api import GraphQLAPI, field
from graphql_mcp.server import GraphQLMCP
class BookAPI:
books = [
{"id": "1", "title": "The Hobbit", "author": "J.R.R. Tolkien"},
{"id": "2", "title": "1984", "author": "George Orwell"}
]
@field
def book(self, id: str) -> dict:
"""Get a book by ID."""
return next((book for book in self.books if book["id"] == id), None)
@field
def books(self) -> list[dict]:
"""Get all books."""
return self.books
@field
def add_book(self, title: str, author: str) -> dict:
"""Add a new book."""
book = {"id": str(len(self.books) + 1), "title": title, "author": author}
self.books.append(book)
return book
api = GraphQLAPI(root_type=BookAPI)
server = GraphQLMCP.from_api(api, name="BookStore")
Remote GraphQL APIs
You can also connect to existing GraphQL APIs:
from graphql_mcp.server import GraphQLMCP
# Connect to a public GraphQL API
server = GraphQLMCP.from_remote_url(
url="https://countries.trevorblades.com/",
name="Countries API"
)
# With authentication
authenticated_server = GraphQLMCP.from_remote_url(
url="https://api.github.com/graphql",
bearer_token="your_github_token",
name="GitHub API"
)
Other GraphQL Libraries
GraphQL MCP works with any GraphQL library that produces a graphql-core schema:
import strawberry
from graphql_mcp.server import GraphQLMCP
@strawberry.type
class Query:
@strawberry.field
def hello(self, name: str = "World") -> str:
return f"Hello, {name}!"
schema = strawberry.Schema(query=Query)
server = GraphQLMCP(schema=schema._schema, name="Strawberry API")
Configuration
server = GraphQLMCP.from_api(
api,
name="My API",
graphql_http=True, # Enable GraphQL HTTP endpoint
allow_mutations=True, # Allow mutation tools
auth=jwt_verifier, # Optional JWT authentication
)
# Serve with custom configuration
app = server.http_app(
transport="streamable-http", # or "http" or "sse"
stateless_http=True, # Don't maintain client state
)
How It Works
- Schema Analysis: GraphQL MCP analyzes your GraphQL schema
- Tool Generation: Each query and mutation becomes an MCP tool
- Type Mapping: GraphQL types are mapped to Python types
- Execution: Tools execute GraphQL operations when called
- HTTP Serving: Both MCP and GraphQL endpoints are served
The generated tools use snake_case naming (e.g., addBook becomes add_book) and preserve all type information and documentation from your GraphQL schema.
MCP Inspector
GraphQL-MCP includes a built-in MCP Inspector that provides a web-based interface for testing and debugging your MCP tools. The inspector is automatically injected into GraphiQL interfaces when serving your GraphQL endpoints.
Features
- Tool Discovery: Browse all available MCP tools generated from your GraphQL schema
- Interactive Testing: Execute tools with custom parameters and see real-time results
- Authentication Support: Test with Bearer tokens, API keys, or custom headers
- Call History: Track and review previous tool executions
- Schema Inspection: View detailed parameter and output schemas for each tool
- Real-time Status: Monitor connection status and tool availability
Accessing the Inspector
When you enable GraphQL HTTP endpoints, the MCP Inspector is automatically available:
server = GraphQLMCP.from_api(
api,
name="My API",
graphql_http=True, # This enables the GraphQL endpoint with MCP Inspector
)
app = server.http_app()
Navigate to your server in a web browser to access the inspector interface.
License
MIT License - see LICENSE file for details.
1 maintainer
Metadata
1 maintainer
Release files for graphql-mcp 1.5.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| graphql_mcp-1.5.1.tar.gz | 303.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| graphql_mcp-1.5.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 341.2 kB
Release files / graphql_mcp-1.5.1.tar.gz
| Download URL | graphql_mcp-1.5.1.tar.gz |
|---|---|
| Size | 303.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6e87c7a8bd93d072dca7e20f547ec0cc79ea36fdc2608e3d96afe984bb8f2348
|
|
BLAKE2b-256 checksum How to use checksums |
0695f90ee4586335919d1725b692f0766d6495c6639b5d16590dfd662013e939
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.8.22
|
Release files / graphql_mcp-1.5.1-py3-none-any.whl
| Download URL | graphql_mcp-1.5.1-py3-none-any.whl |
|---|---|
| Size | 37.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6a92d34d88ea39d9d1bf44b2c48033fad5742adc5efb9e37f1985f4786659d2f
|
|
BLAKE2b-256 checksum How to use checksums |
0fd3b53c9f5bd4db39541a803a59f75b84f1b59aaf02e3f818df19afc2f73e3d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.8.22
|
