GraphQL MCP Server

MCP server for GraphQL — schema introspection, auto-generated tools, query/mutation execution for Claude, Cursor, and AI agents.

What It Does

Connects to any GraphQL endpoint and gives AI agents the ability to:

• Introspect schemas — discover all types, queries, mutations, and subscriptions
• Execute queries and mutations — raw GraphQL strings or typed field-based calls
• Search and explore — find types, fields, and arguments across the schema
• Manage connections — switch endpoints, configure auth, cache schemas

Quick Start

npx @supernova123/graphql-mcp-server

Set your endpoint via environment variable:

GRAPHQL_ENDPOINT=https://your-api.com/graphql npx @supernova123/graphql-mcp-server

Or configure at runtime with the connect_endpoint tool.

Tools (20)

Connection & Configuration

Schema Introspection

Execution

Cache Management

Environment Variables

Configuration (Claude Desktop)

{
  "mcpServers": {
    "graphql": {
      "command": "npx",
      "args": ["-y", "@supernova123/graphql-mcp-server"],
      "env": {
        "GRAPHQL_ENDPOINT": "https://your-api.com/graphql",
        "GRAPHQL_AUTH_TOKEN": "***"
      }
    }
  }
}

Features

• No external GraphQL library — minimal dependency surface, works at the HTTP layer
• Schema caching — introspect once, reuse across tool calls
• Retry with backoff — transient errors (5xx, 429, timeouts) are retried automatically
• Output sanitization — ANSI stripping and length capping prevent prompt injection
• Type-safe — TypeScript with Zod validation on all tool inputs
• Auth flexibility — Bearer tokens, Basic auth, or arbitrary HTTP headers

Development

npm install
npm run build
npm test

Blog Posts

Real data from building and running this server:

• What 6,000 npm Downloads Taught Me — distribution and growth data
• The MCP Server Naming Playbook — how naming affects discoverability

License

MIT