drestrepom/mcp_graphql

An MCP (Model Context Protocol) server that enables interaction with GraphQL APIs.
Description
MCP GraphQL is a tool that implements the Model Context Protocol (MCP) to provide a standardized interface for interacting with GraphQL APIs. It automatically exposes each GraphQL query as a separate MCP tool, allowing MCP-compatible clients to seamlessly communicate with GraphQL services.
Features
- Each GraphQL query is exposed as a distinct MCP tool
- Tool parameters automatically match the corresponding GraphQL query parameters
- JSON schema for tool inputs is dynamically generated from GraphQL query parameters
- No schema definition required - simply provide the API URL and credentials
- Currently supports GraphQL queries (mutations support planned for future releases)
- Configurable authentication (Bearer, Basic, custom headers)
- Automatic handling of complex GraphQL types
Requirements
- Python 3.11 or higher
Installation
Using uv (recommended)
When using uv no specific installation is needed. We will
use uvx to directly run *mcp-graphql*.
Using pip
Alternatively you can install mcp-graphql via pip:
Installation from source code
Usage
As a command line tool
Using uvx:
Using pip installation:
or
Available options
- --api-url: GraphQL API URL (required)
- --auth-token: Authentication token (optional, can also be set via MCP_AUTH_TOKEN environment variable)
- --auth-type: Authentication type, default is "Bearer" (optional)
- --auth-headers: Custom authentication headers in JSON format (optional)
- --queries-file: Path to a .gql file containing predefined GraphQL queries (optional)
- --queries: Predefined GraphQL queries passed directly as a string (optional)
- --max-depth: Maximum depth when auto-generating queries (default: 5)
Example with custom headers:
Example with predefined queries file:
Example passing queries directly as a string (use single quotes to avoid shell conflicts):
About automatic query generation
If neither --queries-file nor --queries is supplied, *mcp-graphql* will
automatically build a query by introspecting the GraphQL schema and selecting
**all** scalar fields up to a configurable depth. This is convenient for
quickly exploring an API, but it has two main drawbacks:
1. **Too much depth** – drilling deep into nested objects (especially lists)
can return a large amount of data and overflow the LLM context window.
2. **Lack of control** – you cannot precisely choose which fields are
included, so tokens may be wasted on irrelevant information.
The --max-depth option mitigates the first issue by limiting the recursion
depth (default = 5). Even so, the best practice is to **define the exact
queries you need** through --queries-file or --queries. In doing so:
* You control exactly which fields are returned and avoid unnecessary lists.
* Every named operation in your file/string is automatically exposed as an MCP
*tool* with no manual boilerplate.
Example using --max-depth to limit the auto-generated query to depth 2: