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

| Tool | Description | |------|-------------| | connect_endpoint | Set or change the active GraphQL endpoint | | set_auth_token | Configure Bearer token authentication | | set_basic_auth | Configure HTTP Basic authentication | | set_headers | Replace custom HTTP headers | | add_header | Add/update a single header | | remove_header | Remove a header | | get_connection_status | Show endpoint config, auth state, and schema cache |

Schema Introspection

| Tool | Description | |------|-------------| | introspect_schema | Fetch the full schema via introspection | | list_types | List all types (filter by kind or name) | | describe_type | Get full details of a single type | | list_queries | List all root query fields | | list_mutations | List all root mutation fields | | list_subscriptions | List all root subscription fields | | describe_field | Get full details of a field | | search_schema | Search types and fields by substring |

Execution

| Tool | Description | |------|-------------| | execute_query | Send a raw GraphQL query | | execute_mutation | Send a raw GraphQL mutation | | execute_typed_query | Execute a query by field name (auto-constructed) | | execute_typed_mutation | Execute a mutation by field name (auto-constructed) |

Cache Management

| Tool | Description | |------|-------------| | get_cached_schema | Return the cached introspection result | | clear_cache | Clear schema cache | | reload_schema | Force a fresh introspection |

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | GRAPHQL_ENDPOINT | GraphQL endpoint URL | (none — must configure at runtime) | | GRAPHQL_AUTH_TOKEN | Bearer token for Authorization header | (none) | | GRAPHQL_BASIC_USER | Basic auth username | (none) | | GRAPHQL_BASIC_PASS | Basic auth password | (none) | | GRAPHQL_TIMEOUT_MS | Request timeout in milliseconds | 30000 | | GRAPHQL_HEADER_* | Custom headers (e.g. GRAPHQL_HEADER_X_API_KEY=secret) | (none) |

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