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
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.
License
MIT License - see LICENSE file for details.
1 maintainer
Metadata
1 maintainer
Release files for graphql-mcp 1.4.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.4.1.tar.gz | 144.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| graphql_mcp-1.4.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 168.8 kB
Release files / graphql_mcp-1.4.1.tar.gz
| Download URL | graphql_mcp-1.4.1.tar.gz |
|---|---|
| Size | 144.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1edbb575e41cec6b4120446a988ec3187d5e82528366042220fc8774fc408534
|
|
BLAKE2b-256 checksum How to use checksums |
6ebbafb93c1ec73073e6867bb82b52abbe98177ab404d51cdf73b98f6e82b261
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.8.22
|
Release files / graphql_mcp-1.4.1-py3-none-any.whl
| Download URL | graphql_mcp-1.4.1-py3-none-any.whl |
|---|---|
| Size | 24.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c381a143f4f4807de76836a59bd2e5a739ad3cd45c01636cd2e27130aa53d797
|
|
BLAKE2b-256 checksum How to use checksums |
b84d3bf6c2235330a2e0eee24980abeb2db5d246f692cc916c33a26f2e4a247f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.8.22
|
