Skip to main content
Glama
graphql-mcp

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.