graphql-mcp


Namegraphql-mcp JSON
Version 1.5.5 PyPI version JSON
download
home_pageNone
SummaryA framework for building Python GraphQL MCP servers.
upload_time2025-10-07 08:52:32
maintainerNone
docs_urlNone
authorNone
requires_python<3.13,>=3.11
licenseMIT
keywords graphql graphql-api graphqlapi server mcp multi-model-protocol
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # 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"
}
        
Elapsed time: 0.53080s