{
  "markdown": "# graphql-to-mcp\n\n[![npm version](https://img.shields.io/npm/v/graphql-to-mcp)](https://www.npmjs.com/package/graphql-to-mcp)\n[![npm downloads](https://img.shields.io/npm/dm/graphql-to-mcp)](https://www.npmjs.com/package/graphql-to-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nTurn any GraphQL API into MCP tools — zero config, zero code.\n\nPoint `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.\n\n## Quick Start\n\n**Try it now** — no install needed:\n\n```bash\nnpx graphql-to-mcp https://countries.trevorblades.com/graphql\n```\n\nOr add to Claude Desktop / Cursor config:\n\n```json\n{\n  \"mcpServers\": {\n    \"countries\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"graphql-to-mcp\", \"https://countries.trevorblades.com/graphql\"]\n    }\n  }\n}\n```\n\nThat's it. Claude can now query countries, continents, and languages.\n\n## Features\n\n- **Zero config** — just provide a GraphQL endpoint URL\n- **Auto-introspection** — discovers all queries and mutations automatically\n- **Flat parameter schemas** — nested `input` objects are flattened for better LLM accuracy\n- **Smart truncation** — large responses are intelligently pruned (array slicing + depth limiting)\n- **Auth support** — Bearer tokens, API keys (header or query)\n- **Retry logic** — automatic retries on 429/5xx with exponential backoff\n- **Include/exclude filters** — expose only the operations you want\n- **Schema caching** — skip re-introspection with `--schema-cache` for faster startup\n- **Mutation safety** — auto-detect destructive mutations (`delete*`, `remove*`, etc.) and warn or block them\n\n## Usage\n\n### CLI\n\n```bash\n# Public API (no auth)\nnpx graphql-to-mcp https://countries.trevorblades.com/graphql\n\n# With bearer token\nnpx graphql-to-mcp https://api.github.com/graphql --bearer ghp_xxxxx\n\n# With API key\nnpx graphql-to-mcp https://api.example.com/graphql --api-key \"X-API-Key:your-key:header\"\n\n# Filter operations\nnpx graphql-to-mcp https://api.example.com/graphql --include \"get*\" --exclude \"internal*\"\n\n# With prefix (avoid name collisions when using multiple APIs)\nnpx graphql-to-mcp https://api.example.com/graphql --prefix myapi\n\n# Cache schema locally for faster restarts\nnpx graphql-to-mcp https://api.example.com/graphql --schema-cache ./schema.json\n\n# Force re-introspection (ignore cache)\nnpx graphql-to-mcp https://api.example.com/graphql --schema-cache ./schema.json --force-refresh\n\n# Block destructive mutations (delete*, remove*, etc.)\nnpx graphql-to-mcp https://api.example.com/graphql --mutation-safety safe\n```\n\n### Claude Desktop / Cursor Config\n\n```json\n{\n  \"mcpServers\": {\n    \"github\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\", \"graphql-to-mcp\",\n        \"https://api.github.com/graphql\",\n        \"--bearer\", \"ghp_xxxxx\",\n        \"--prefix\", \"github\"\n      ]\n    }\n  }\n}\n```\n\n### Programmatic\n\n```typescript\nimport { createServer } from \"graphql-to-mcp\";\n\nconst server = await createServer({\n  endpoint: \"https://api.example.com/graphql\",\n  auth: { type: \"bearer\", token: \"xxx\" },\n  include: [\"getUser\", \"listUsers\"],\n});\n```\n\n## How It Works\n\n1. **Introspect** — Fetches the GraphQL schema via introspection query\n2. **Flatten** — Nested `InputObject` types are flattened into simple key-value parameters (e.g., `input.name` → `input_name`)\n3. **Generate** — Each query/mutation becomes an MCP tool with a flat JSON Schema\n4. **Execute** — When an LLM calls a tool, the flat args are reconstructed into proper GraphQL variables and sent to your endpoint\n\n### Why Flat Schemas?\n\nLLMs are significantly better at filling flat key-value parameters than deeply nested JSON objects. By flattening `InputObject` types, we get:\n\n- Higher accuracy in parameter filling\n- Fewer hallucinated nested structures\n- Better compatibility across different LLM providers\n\n## Options\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--bearer <token>` | Bearer token auth | — |\n| `--api-key <name:value:in>` | API key auth | — |\n| `-H, --header <name:value>` | Custom header (repeatable) | — |\n| `--include <pattern>` | Include only matching operations | all |\n| `--exclude <pattern>` | Exclude matching operations | none |\n| `--prefix <name>` | Tool name prefix | — |\n| `--timeout <ms>` | Request timeout | 30000 |\n| `--max-retries <n>` | Retry on 429/5xx | 3 |\n| `--transport <stdio\\|sse>` | MCP transport | stdio |\n| `--schema-cache <path>` | Save/load introspection cache | — |\n| `--force-refresh` | Ignore cache, re-introspect | false |\n| `--mutation-safety <mode>` | `warn` \\| `safe` \\| `unrestricted` | warn |\n\n## Smart Truncation\n\nGraphQL APIs can return large payloads that overwhelm LLM context windows. `graphql-to-mcp` automatically:\n\n- **Slices arrays** to 20 items (with metadata showing total count)\n- **Prunes depth** beyond 5 levels (with object/array summaries)\n- **Hard truncates** at 50K characters as a safety net\n\n## Schema Caching\n\nIntrospection queries can be slow on large schemas. Use `--schema-cache` to save the introspection result locally:\n\n```bash\n# First run: introspects and saves to cache\nnpx graphql-to-mcp https://api.example.com/graphql --schema-cache ./schema.json\n\n# Subsequent runs: loads from cache (instant startup)\nnpx graphql-to-mcp https://api.example.com/graphql --schema-cache ./schema.json\n\n# Force re-introspection when the API schema changes\nnpx graphql-to-mcp https://api.example.com/graphql --schema-cache ./schema.json --force-refresh\n```\n\nThe cache file stores the endpoint URL and timestamp. If you point at a different endpoint, it automatically re-introspects.\n\n## Mutation Safety\n\nBy default, `graphql-to-mcp` detects destructive mutations and adds warnings to their descriptions. This helps LLMs understand the risk before executing them.\n\nDetected patterns: `delete*`, `remove*`, `drop*`, `clear*`, `truncate*`, `destroy*`, `purge*`, `reset*` (case-insensitive).\n\n| Mode | Behavior |\n|------|----------|\n| `warn` (default) | Adds \"DESTRUCTIVE:\" prefix to dangerous mutation descriptions |\n| `safe` | Completely excludes dangerous mutations from the tool list |\n| `unrestricted` | No filtering or warnings (previous behavior) |\n\n```bash\n# Safe mode: only expose read queries + non-destructive mutations\nnpx graphql-to-mcp https://api.example.com/graphql --mutation-safety safe\n\n# Unrestricted: expose everything (use with caution)\nnpx graphql-to-mcp https://api.example.com/graphql --mutation-safety unrestricted\n```\n\n## Use with REST APIs Too\n\nPair with [mcp-openapi](https://www.npmjs.com/package/mcp-openapi) to give Claude access to both REST and GraphQL APIs:\n\n```json\n{\n  \"mcpServers\": {\n    \"github-graphql\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"graphql-to-mcp\", \"https://api.github.com/graphql\", \"--bearer\", \"ghp_xxx\", \"--prefix\", \"gh\"]\n    },\n    \"petstore-rest\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-openapi\", \"https://petstore3.swagger.io/api/v3/openapi.json\"]\n    }\n  }\n}\n```\n\n## Related\n\n- [mcp-openapi](https://www.npmjs.com/package/mcp-openapi) — Same zero-config approach for REST/OpenAPI APIs\n\n## License\n\nMIT\n",
  "bytes": 7215,
  "sha": "931af3f8fb4ab230fd2541782608d9e9be552286b72571c7032aa5c25c7ff1da",
  "repo_slug": "docat0209/mcp-graphql",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_docat0209_graphql_079db226/readme"
}