graphql-to-mcp

Turn any GraphQL API into MCP tools — zero config, zero code.

Point graphql-to-mcp at a GraphQL endpoint and it auto-generates one MCP tool per query/mutation via introspection. Works with Claude Desktop, Cursor, Windsurf, and any MCP client.

Quick Start

Try it now — no install needed:

npx graphql-to-mcp https://countries.trevorblades.com/graphql

Or add to Claude Desktop / Cursor config:

{
  "mcpServers": {
    "countries": {
      "command": "npx",
      "args": ["-y", "graphql-to-mcp", "https://countries.trevorblades.com/graphql"]
    }
  }
}

That's it. Claude can now query countries, continents, and languages.

Features

• Zero config — just provide a GraphQL endpoint URL
• Auto-introspection — discovers all queries and mutations automatically
• Flat parameter schemas — nested input objects are flattened for better LLM accuracy
• Smart truncation — large responses are intelligently pruned (array slicing + depth limiting)
• Auth support — Bearer tokens, API keys (header or query)
• Retry logic — automatic retries on 429/5xx with exponential backoff
• Include/exclude filters — expose only the operations you want

Usage

CLI

# Public API (no auth)
npx graphql-to-mcp https://countries.trevorblades.com/graphql

# With bearer token
npx graphql-to-mcp https://api.github.com/graphql --bearer ghp_xxxxx

# With API key
npx graphql-to-mcp https://api.example.com/graphql --api-key "X-API-Key:your-key:header"

# Filter operations
npx graphql-to-mcp https://api.example.com/graphql --include "get*" --exclude "internal*"

# With prefix (avoid name collisions when using multiple APIs)
npx graphql-to-mcp https://api.example.com/graphql --prefix myapi

Claude Desktop / Cursor Config

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y", "graphql-to-mcp",
        "https://api.github.com/graphql",
        "--bearer", "ghp_xxxxx",
        "--prefix", "github"
      ]
    }
  }
}

Programmatic

import { createServer } from "graphql-to-mcp";

const server = await createServer({
  endpoint: "https://api.example.com/graphql",
  auth: { type: "bearer", token: "xxx" },
  include: ["getUser", "listUsers"],
});

How It Works

1. Introspect — Fetches the GraphQL schema via introspection query
2. Flatten — Nested InputObject types are flattened into simple key-value parameters (e.g., input.name → input_name)
3. Generate — Each query/mutation becomes an MCP tool with a flat JSON Schema
4. Execute — When an LLM calls a tool, the flat args are reconstructed into proper GraphQL variables and sent to your endpoint

Why Flat Schemas?

LLMs are significantly better at filling flat key-value parameters than deeply nested JSON objects. By flattening InputObject types, we get:

• Higher accuracy in parameter filling
• Fewer hallucinated nested structures
• Better compatibility across different LLM providers

Options

| Option | Description | Default | |--------|-------------|---------| | --bearer <token> | Bearer token auth | — | | --api-key <name:value:in> | API key auth | — | | -H, --header <name:value> | Custom header (repeatable) | — | | --include <pattern> | Include only matching operations | all | | --exclude <pattern> | Exclude matching operations | none | | --prefix <name> | Tool name prefix | — | | --timeout <ms> | Request timeout | 30000 | | --max-retries <n> | Retry on 429/5xx | 3 | | --transport <stdio\|sse> | MCP transport | stdio |

Smart Truncation

GraphQL APIs can return large payloads that overwhelm LLM context windows. graphql-to-mcp automatically:

• Slices arrays to 20 items (with metadata showing total count)
• Prunes depth beyond 5 levels (with object/array summaries)
• Hard truncates at 50K characters as a safety net

Use with REST APIs Too

Pair with mcp-openapi to give Claude access to both REST and GraphQL APIs:

{
  "mcpServers": {
    "github-graphql": {
      "command": "npx",
      "args": ["-y", "graphql-to-mcp", "https://api.github.com/graphql", "--bearer", "ghp_xxx", "--prefix", "gh"]
    },
    "petstore-rest": {
      "command": "npx",
      "args": ["-y", "mcp-openapi", "https://petstore3.swagger.io/api/v3/openapi.json"]
    }
  }
}

Pre-built MCP Servers

Don't want to configure APIs yourself? These ready-to-use .mcpb plugins connect Claude to popular services in one click:

| Plugin | What it does | Price | |--------|-------------|-------| | AI Crypto Tracker | Ask Claude about Bitcoin, ETH, 10,000+ coins — prices, trends, market cap | ~~$14~~ $9 | | AI Stripe Dashboard | Ask Claude your MRR, subscriptions, invoices — read-only, safe | ~~$24~~ $15 | | AI Weather Assistant | Ask Claude about weather forecasts anywhere in the world | Free |

All plugins use one-click .mcpb install for Claude Desktop — no terminal, no config files needed.

Related

• mcp-openapi — Same zero-config approach for REST/OpenAPI APIs
• CLAUDE.md Templates — 32 production-ready instruction files for Claude Code

License

MIT