Skip to main content
Glama
GraphQL MCP Server

GraphQL MCP Server

GraphQL MCP Server

npm License: MIT Glama

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

Related MCP server: mcp-graphql-tools

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:

License

MIT

Available Tools

22 tools
add_headerA
Idempotent

Add or update a single custom HTTP header without replacing the others. Useful for one-off headers like X-Trace-Id. To remove, use remove_header.

Inputs: key (required), value (required).

clear_cacheA
Idempotent

Clear the schema cache. If endpoint is given, clears only that endpoint's cache; otherwise clears all. Use this to free memory after switching endpoints, or to force a fresh introspection on the next call.

Inputs: endpoint.

connect_endpointA
Idempotent

Set or change the active GraphQL endpoint. All subsequent tool calls (introspect, query, mutate) target this endpoint. Replaces the previous client; existing schema cache for the old endpoint is kept but a new schema will be fetched for the new one. Use set_auth_token / set_headers immediately after to configure credentials. If the endpoint requires CORS for browser access, that is the caller's responsibility — the MCP server is a backend process.

Inputs: endpoint (required), timeout_ms.

describe_fieldA
Read-onlyIdempotent

Get full details of a single field on any type: description, return type, arguments (each with name, type, description, default value), and deprecation info. Pass type_name='Query' or 'Mutation' to look up root operations, or pass any object type name to look up one of its fields.

Inputs: type_name (required), field_name (required).

describe_typeA
Read-onlyIdempotent

Get full details of a single type: all fields (with their args and return types), input fields, interfaces, enum values, and possible types. Use this to understand a type's shape before constructing a query. Pass the name of any type — including root types like 'Query' or 'Mutation', input types like 'CreateUserInput', or scalar types.

Inputs: type_name (required), include_deprecated.

execute_mutationA

Send a raw GraphQL mutation string to the endpoint. Functionally identical to execute_query — use whichever is more semantically clear. Not idempotent: mutations can have side effects.

Inputs: mutation (required), variables, operation_name.

execute_queryA
Read-onlyIdempotent

Send a raw GraphQL query string to the endpoint. Use this when you already have a complete query — for example, one written by a human or copied from API docs. Returns the data field of the response, or a structured error message if the server returned errors. Variables are passed through as-is. Idempotent: same query → same result (for read-only queries).

Inputs: query (required), variables, operation_name.

execute_typed_mutationA

Execute a mutation by field name. Looks up the field on the root Mutation type, validates arguments, and constructs the mutation. If selection is omitted, defaults to __typename. Not idempotent — mutations can have side effects.

Inputs: field (required), variables, selection.

execute_typed_queryA
Read-onlyIdempotent

Execute a query by field name. Looks up the field on the root Query type using the introspected schema, validates that the variables you pass match the field's argument types (by name), and constructs a query string automatically. If you don't provide a selection set, the server auto-builds one with __typename plus scalar fields. Requires the schema to be introspected first.

Inputs: field (required), variables, selection, include_deprecated.

get_cached_schemaA
Read-onlyIdempotent

Return the cached introspection result for the current endpoint as JSON. Use this when you need the full schema in one shot (e.g. to build a query offline). For large schemas this can be 1MB+ — use describe_type / list_queries / search_schema for targeted access. The max_depth parameter caps type traversal to keep output size bounded.

Inputs: include_system_types, max_depth.

get_connection_statusA
Read-onlyIdempotent

Show the current endpoint, configured headers (with secrets masked), auth state, and schema cache state. Set ping=true to also send a {__typename} query to verify the endpoint is reachable and measure latency.

Inputs: ping.

introspect_schemaA
Read-onlyIdempotent

Fetch the full GraphQL schema via introspection and cache it. Required before any list_*, describe_*, or execute_typed_* call. Idempotent: returns the cached schema if available unless force=true. The schema can be large (>1MB for Shopify/GitHub) so consider clearing the cache or using search/describe tools on subsequent calls.

Inputs: force.

list_mutationsA
Read-onlyIdempotent

List all root mutation fields (e.g. createUser, updatePost). Each entry shows the return type and argument types. Returns an empty list if the schema has no mutation type. Use search= to filter by name.

Inputs: search, limit.

list_queriesA
Read-onlyIdempotent

List all root query fields (e.g. user, posts, search). Each entry shows the field's return type and its argument types. Use describe_field to get more detail on a specific query. Use search= to filter by name substring.

Inputs: search, limit.

list_subscriptionsA
Read-onlyIdempotent

List all root subscription fields (e.g. messageAdded, onUserUpdate). Note: this MCP server uses HTTP request/response, so subscriptions cannot be executed here — list is informational only. Use a websocket-based GraphQL client to consume subscriptions. Returns an empty list if the schema has no subscription type.

Inputs: search, limit.

list_typesA
Read-onlyIdempotent

List all types in the introspected schema. Filter by kind (OBJECT, SCALAR, INTERFACE, UNION, ENUM, INPUT_OBJECT) or by name substring. Excludes introspection system types (those starting with __) by default. Use describe_type to get full details for a specific type.

Inputs: kind, search, limit.

reload_schemaA
Idempotent

Force a fresh introspection, replacing any cached schema for the given endpoint (or the current one if not specified). Use this when you suspect the remote schema has changed.

Inputs: endpoint.

remove_headerA
Idempotent

Remove a custom HTTP header. Does not affect Authorization (use set_auth_token with empty string).

Inputs: key (required).

search_schemaA
Read-onlyIdempotent

Search the entire schema for types, fields, input fields, and enum values matching a substring (case-insensitive). Useful for finding things by partial name when the schema is large. Returns up to 100 hits by default.

Inputs: term (required), limit.

set_auth_tokenA
Idempotent

Set a bearer token to send in the Authorization header on every request. Pass an empty string to clear. The token is held in process memory and never logged. For Basic auth or arbitrary headers, use set_basic_auth or set_headers / add_header instead.

Inputs: token (required).

set_basic_authA
Idempotent

Configure HTTP Basic authentication. Replaces any bearer token. Pass empty username + password to clear.

Inputs: username (required), password (required).

set_headersA
Idempotent

Replace the full set of custom HTTP headers. Use this for X-API-Key, X-Tenant, X-Trace-Id, etc. Authorization is handled separately by set_auth_token / set_basic_auth and will be re-applied on top of these headers. Pass an empty object to clear all custom headers.

Inputs: headers (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 22 tools

    Disambiguation5/5

    Every tool has a clearly distinct purpose: connection management, authentication, schema introspection, typed execution, and raw execution. There is no overlap or ambiguity between any pair of tools.

    Naming Consistency5/5

    Tool names consistently follow a verb_noun pattern with underscores (e.g., connect_endpoint, list_queries, execute_typed_mutation). Minor variations like 'reload_schema' vs 'introspect_schema' are still consistent in style.

    Tool Count4/5

    At 22 tools, the set is on the higher side of reasonable for a comprehensive GraphQL client server. While each tool serves a justifiable purpose, the count exceeds the typical well-scoped range of 3-15, making it slightly heavy but not excessive.

    Completeness5/5

    The tool surface covers the full lifecycle: connection setup, authentication (token, basic, custom headers), schema introspection, exploration (list, describe, search), query/mutation execution (raw and typed), and cache management. Subscriptions are omitted with a valid explanation. No obvious gaps.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to interact with Hasura GraphQL endpoints to discover schema structures and execute queries or mutations. It provides specialized tools for table introspection, data previewing, and performing data aggregations through natural language.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to interact with any GraphQL API by introspecting the schema and exposing queries and mutations as MCP tools, with built-in pagination, semantic search, and framework adapters.
      29 npm
      MIT