# 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 } } }
```