MCP GraphQL

Exposes GraphQL queries as MCP tools with auto-generated inputs and flexible authentication for GraphQL APIs.

python

19

GitHub Stars

python

Language

6 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "drestrepom-mcp_graphql": {
      "command": "uvx",
      "args": [
        "mcp-graphql",
        "--api-url",
        "https://api.example.com/graphql"
      ],
      "env": {
        "MCP_AUTH_TOKEN": "your-token"
      }
    }
  }
}

MCP GraphQL provides a standardized MCP interface over GraphQL APIs by exposing each GraphQL query as a separate MCP tool. You can browse available queries as tools, supply parameters that map to the queries, and authenticate as needed to retrieve data from GraphQL services.

How to use

Connect to a GraphQL API through an MCP client and interact with each query as an individual tool. You provide the tool name (corresponding to a query) and supply inputs that match the query’s parameters. The server handles converting tool calls into GraphQL queries, executing them against your API, and returning the results. You can authenticate using a Bearer token or custom headers if your API requires them.

How to install

Prer equisites you need on your system:

Python 3.11 or higher for building or running the server from source.

You have several ways to run MCP GraphQL. Choose one that fits your environment.

Installation from source and binary options

# Clone the project
git clone https://github.com/your-username/mcp_graphql.git
cd mcp_graphql

# Install dependencies
pip install .

Run options (stdio mode)

# Using uvx
uvx mcp-graphql --api-url="https://api.example.com/graphql"

# Using python module
python -m mcp_graphql --api-url="https://api.example.com/graphql"

Run options (http/remote)

If you prefer to run the MCP server via a container, use the docker-based command shown in the run examples.

Environment and authentication

You can supply an authentication token via a command option or environment variable. The MCP_AUTH_TOKEN environment variable is supported to avoid placing tokens in command lines.

Configuration notes

The server automatically exposes each GraphQL query as a distinct MCP tool. Tool inputs are derived from the query parameters, and a JSON schema for inputs is created dynamically. Mutations are planned for future releases.

Security considerations

Use secure endpoints (https) and restrict access to clients that require your data. When using Bearer tokens, rotate credentials periodically and prefer environment variables over in-command tokens where possible.

Examples and next steps

Define your own predefined queries or allow automatic generation with a depth limit to avoid overly large results. For quick exploration, you can start with the automatic generation feature and then supply explicit queries for production use to control returned fields and token usage.