# GraphQL-MCP
A library for automatically generating [FastMCP](https://pypi.org/project/fastmcp/) tools from GraphQL APIs using [graphql-api](https://pypi.org/project/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:
```bash
pip install graphql-mcp graphql-api
```
Create a simple GraphQL API and expose it as MCP tools:
```python
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](https://github.com/parob/graphql-api) library, which provides a simple, decorator-based approach to building GraphQL APIs:
```python
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:
```python
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:
```python
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
```python
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
1. **Schema Analysis**: GraphQL MCP analyzes your GraphQL schema
2. **Tool Generation**: Each query and mutation becomes an MCP tool
3. **Type Mapping**: GraphQL types are mapped to Python types
4. **Execution**: Tools execute GraphQL operations when called
5. **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.
<img src="docs/mcp_inspector.png" alt="MCP Inspector Interface" width="600">
### 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:
```python
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](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "graphql-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.11",
"maintainer_email": null,
"keywords": "GraphQL, GraphQL-API, GraphQLAPI, Server, MCP, Multi-Model-Protocol",
"author": null,
"author_email": "Robert Parker <rob@parob.com>",
"download_url": "https://files.pythonhosted.org/packages/f4/1f/4d5afd34133284f407ec554eefeb44da27d157e7f7f0d68e4924360fb1ef/graphql_mcp-1.5.5.tar.gz",
"platform": null,
"description": "# GraphQL-MCP\n\nA library for automatically generating [FastMCP](https://pypi.org/project/fastmcp/) tools from GraphQL APIs using [graphql-api](https://pypi.org/project/graphql-api/).\n\nThis allows you to expose your GraphQL API as MCP tools that can be used by AI agents and other systems.\n\n## Quick Start\n\nInstall graphql-mcp with graphql-api:\n\n```bash\npip install graphql-mcp graphql-api\n```\n\nCreate a simple GraphQL API and expose it as MCP tools:\n\n```python\nimport asyncio\nimport uvicorn\n\nfrom graphql_api import GraphQLAPI, field\nfrom graphql_mcp.server import GraphQLMCP\n\n\nclass HelloWorldAPI:\n\n @field\n def hello(self, name: str = \"World\") -> str:\n return f\"Hello, {name}!\"\n\n\napi = GraphQLAPI(root_type=HelloWorldAPI)\n\nserver = GraphQLMCP.from_api(api)\n\nmcp_app = server.http_app(\n transport=\"streamable-http\",\n stateless_http=True\n)\n\n\nif __name__ == \"__main__\":\n uvicorn.run(mcp_app, host=\"0.0.0.0\", port=8002)\n```\n\nThat's it! Your GraphQL API is now available as MCP tools.\n\n## Features\n\n- **Automatic Tool Generation**: Converts GraphQL queries and mutations into MCP tools\n- **Type-Safe**: Maps GraphQL types to Python types with full type hints\n- **Built-in HTTP Server**: Serves both MCP and GraphQL endpoints\n- **Authentication**: Supports JWT and bearer token authentication\n- **Remote GraphQL**: Connect to existing GraphQL APIs\n- **Production Ready**: Built on FastMCP and Starlette\n- **Built-in MCP Inspector**: Web-based GraphiQL interface for testing and debugging\n\n## Usage with graphql-api\n\nThe recommended way to use GraphQL MCP is with the [graphql-api](https://github.com/parob/graphql-api) library, which provides a simple, decorator-based approach to building GraphQL APIs:\n\n```python\nfrom graphql_api import GraphQLAPI, field\nfrom graphql_mcp.server import GraphQLMCP\n\nclass BookAPI:\n books = [\n {\"id\": \"1\", \"title\": \"The Hobbit\", \"author\": \"J.R.R. Tolkien\"},\n {\"id\": \"2\", \"title\": \"1984\", \"author\": \"George Orwell\"}\n ]\n\n @field\n def book(self, id: str) -> dict:\n \"\"\"Get a book by ID.\"\"\"\n return next((book for book in self.books if book[\"id\"] == id), None)\n\n @field\n def books(self) -> list[dict]:\n \"\"\"Get all books.\"\"\"\n return self.books\n\n @field\n def add_book(self, title: str, author: str) -> dict:\n \"\"\"Add a new book.\"\"\"\n book = {\"id\": str(len(self.books) + 1), \"title\": title, \"author\": author}\n self.books.append(book)\n return book\n\napi = GraphQLAPI(root_type=BookAPI)\nserver = GraphQLMCP.from_api(api, name=\"BookStore\")\n```\n\n## Remote GraphQL APIs\n\nYou can also connect to existing GraphQL APIs:\n\n```python\nfrom graphql_mcp.server import GraphQLMCP\n\n# Connect to a public GraphQL API\nserver = GraphQLMCP.from_remote_url(\n url=\"https://countries.trevorblades.com/\",\n name=\"Countries API\"\n)\n\n# With authentication\nauthenticated_server = GraphQLMCP.from_remote_url(\n url=\"https://api.github.com/graphql\",\n bearer_token=\"your_github_token\",\n name=\"GitHub API\"\n)\n```\n\n## Other GraphQL Libraries\n\nGraphQL MCP works with any GraphQL library that produces a `graphql-core` schema:\n\n```python\nimport strawberry\nfrom graphql_mcp.server import GraphQLMCP\n\n@strawberry.type\nclass Query:\n @strawberry.field\n def hello(self, name: str = \"World\") -> str:\n return f\"Hello, {name}!\"\n\nschema = strawberry.Schema(query=Query)\nserver = GraphQLMCP(schema=schema._schema, name=\"Strawberry API\")\n```\n\n## Configuration\n\n```python\nserver = GraphQLMCP.from_api(\n api,\n name=\"My API\",\n graphql_http=True, # Enable GraphQL HTTP endpoint\n allow_mutations=True, # Allow mutation tools\n auth=jwt_verifier, # Optional JWT authentication\n)\n\n# Serve with custom configuration\napp = server.http_app(\n transport=\"streamable-http\", # or \"http\" or \"sse\"\n stateless_http=True, # Don't maintain client state\n)\n```\n\n## How It Works\n\n1. **Schema Analysis**: GraphQL MCP analyzes your GraphQL schema\n2. **Tool Generation**: Each query and mutation becomes an MCP tool\n3. **Type Mapping**: GraphQL types are mapped to Python types\n4. **Execution**: Tools execute GraphQL operations when called\n5. **HTTP Serving**: Both MCP and GraphQL endpoints are served\n\nThe generated tools use `snake_case` naming (e.g., `addBook` becomes `add_book`) and preserve all type information and documentation from your GraphQL schema.\n\n## MCP Inspector\n\nGraphQL-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.\n\n<img src=\"docs/mcp_inspector.png\" alt=\"MCP Inspector Interface\" width=\"600\">\n\n### Features\n\n- **Tool Discovery**: Browse all available MCP tools generated from your GraphQL schema\n- **Interactive Testing**: Execute tools with custom parameters and see real-time results\n- **Authentication Support**: Test with Bearer tokens, API keys, or custom headers\n- **Call History**: Track and review previous tool executions\n- **Schema Inspection**: View detailed parameter and output schemas for each tool\n- **Real-time Status**: Monitor connection status and tool availability\n\n### Accessing the Inspector\n\nWhen you enable GraphQL HTTP endpoints, the MCP Inspector is automatically available:\n\n```python\nserver = GraphQLMCP.from_api(\n api,\n name=\"My API\",\n graphql_http=True, # This enables the GraphQL endpoint with MCP Inspector\n)\n\napp = server.http_app()\n```\n\nNavigate to your server in a web browser to access the inspector interface.\n\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A framework for building Python GraphQL MCP servers.",
"version": "1.5.5",
"project_urls": {
"Homepage": "https://gitlab.com/parob/graphql-mcp",
"Repository": "https://gitlab.com/parob/graphql-mcp"
},
"split_keywords": [
"graphql",
" graphql-api",
" graphqlapi",
" server",
" mcp",
" multi-model-protocol"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "72458c4fd2b62ce727da8058e30854f40149c2f9cfdbf141cd4129d0846a4734",
"md5": "f790a4e624d75b6a25a7589477983638",
"sha256": "9e45869380d425dd1278a9c4b80da1b89ed94edf0d4c2f9e93e8c4f6344d08b9"
},
"downloads": -1,
"filename": "graphql_mcp-1.5.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f790a4e624d75b6a25a7589477983638",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.11",
"size": 37851,
"upload_time": "2025-10-07T08:52:31",
"upload_time_iso_8601": "2025-10-07T08:52:31.239050Z",
"url": "https://files.pythonhosted.org/packages/72/45/8c4fd2b62ce727da8058e30854f40149c2f9cfdbf141cd4129d0846a4734/graphql_mcp-1.5.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f41f4d5afd34133284f407ec554eefeb44da27d157e7f7f0d68e4924360fb1ef",
"md5": "1f9a184804a4ca6c2b9820af64d34a17",
"sha256": "d20f99ba5a127476f234c22ebe9d2b11b202e6cfaaddfe6d8aa67efe6c8c171c"
},
"downloads": -1,
"filename": "graphql_mcp-1.5.5.tar.gz",
"has_sig": false,
"md5_digest": "1f9a184804a4ca6c2b9820af64d34a17",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.11",
"size": 323497,
"upload_time": "2025-10-07T08:52:32",
"upload_time_iso_8601": "2025-10-07T08:52:32.639503Z",
"url": "https://files.pythonhosted.org/packages/f4/1f/4d5afd34133284f407ec554eefeb44da27d157e7f7f0d68e4924360fb1ef/graphql_mcp-1.5.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-07 08:52:32",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "parob",
"gitlab_project": "graphql-mcp",
"lcname": "graphql-mcp"
}