graphql-to-mcp

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

Pointgraphql-to-mcpat 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.

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.

- Zero config— just provide a GraphQL endpoint URL
- Auto-introspection— discovers all queries and mutations automatically
- Flat parameter schemas— nestedinputobjects 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
- Schema caching— skip re-introspection with--schema-cachefor faster startup
- Mutation safety— auto-detect destructive mutations (delete,remove, etc.) and warn or block them

# 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 # Cache schema locally for faster restarts npx graphql-to-mcp https://api.example.com/graphql --schema-cache ./schema.json # Force re-introspection (ignore cache) npx graphql-to-mcp https://api.example.com/graphql --schema-cache ./schema.json --force-refresh # Block destructive mutations (delete, remove, etc.) npx graphql-to-mcp https://api.example.com/graphql --mutation-safety safe

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

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

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

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

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

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

- Slices arraysto 20 items (with metadata showing total count)
- Prunes depthbeyond 5 levels (with object/array summaries)
- Hard truncatesat 50K characters as a safety net

Introspection queries can be slow on large schemas. Use--schema-cacheto save the introspection result locally:

# First run: introspects and saves to cache npx graphql-to-mcp https://api.example.com/graphql --schema-cache ./schema.json # Subsequent runs: loads from cache (instant startup) npx graphql-to-mcp https://api.example.com/graphql --schema-cache ./schema.json # Force re-introspection when the API schema changes npx graphql-to-mcp https://api.example.com/graphql --schema-cache ./schema.json --force-refresh

The cache file stores the endpoint URL and timestamp. If you point at a different endpoint, it automatically re-introspects.

By default,graphql-to-mcpdetects destructive mutations and adds warnings to their descriptions. This helps LLMs understand the risk before executing them.

Detected patterns:delete,remove,drop,clear,truncate,destroy,purge,reset(case-insensitive).

# Safe mode: only expose read queries + non-destructive mutations npx graphql-to-mcp https://api.example.com/graphql --mutation-safety safe # Unrestricted: expose everything (use with caution) npx graphql-to-mcp https://api.example.com/graphql --mutation-safety unrestricted

Pair withmcp-openapito 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"] } } }

- mcp-openapi— Same zero-config approach for REST/OpenAPI APIs

A command-line tool for interacting with Shopify's Admin GraphQL API, Functions, and Polaris Web Components.