graphql-mcp
README.md
# graphql-mcp
MCP server that exposes any GraphQL API as a single `graphql` tool. Works with Claude Code, Cursor, and any MCP client.
## Setup
```bash
uv sync
```
## Configuration
All configuration is via environment variables:
| Variable | Required | Description |
|---|---|---|
| `GRAPHQL_API_URL` | Yes | The GraphQL endpoint URL |
| `GRAPHQL_API_KEY` | Yes | API key or token for authentication |
| `GRAPHQL_AUTH_HEADER` | No | Header name for auth (default: `Authorization`) |
| `GRAPHQL_TIMEOUT` | No | Request timeout in seconds (default: `30`) |
## Usage with Claude Code
```bash
claude --mcp-config mcp.json
```
Where `mcp.json` contains:
```json
{
"mcpServers": {
"graphql": {
"command": "uv",
"args": ["run", "--directory", "/path/to/graphql-mcp", "python", "main.py"],
"env": {
"GRAPHQL_API_URL": "https://api.example.com/graphql",
"GRAPHQL_API_KEY": "your-api-key"
}
}
}
}
```
## Tool
### `graphql`
Execute any GraphQL query or mutation.
**Parameters:**
- `query` (string, required) — A GraphQL query or mutation document
- `variables` (object, optional) — GraphQL variables
**Examples:**
```graphql
# Query
query { viewer { id name email } }
# Mutation with variables
mutation($id: String!, $body: String!) {
commentCreate(input: { issueId: $id, body: $body }) {
success
}
}
# Introspection
query { __type(name: "Mutation") { fields { name } } }
```
TDQS
B3.4/5.0
Scored across 1 tool
Disambiguation5/5
With only one tool, there is no possibility of confusion between tools. The tool's purpose is clear: execute GraphQL queries or mutations.
Naming Consistency4/5
The single tool name 'graphql' is not a verb_noun pattern, but there is no inconsistency to penalize. It is readable and directly reflects the tool's function.
Tool Count4/5
One tool feels thin compared to a typical MCP server, but for a generic GraphQL executor, a single tool can be sufficient. It is slightly under the standard range but reasonable.
Completeness5/5
The tool can execute any GraphQL query or mutation, including introspection, covering the full domain of GraphQL operations. There are no obvious gaps for the server's stated purpose.