mcp-graphql

The server exposes the GraphQL schema as a resource named graphql-schema. This allows clients to access the schema definition directly. The source of this resource is determined by the following priority:

1. A local schema file specified via the SCHEMA environment variable.
2. A schema file hosted at a URL specified via the SCHEMA environment variable.
3. An introspection query performed against the ENDPOINT.

You can install the mcp-graphql server using Smithery for automatic Claude Desktop configuration, or manually by adding it to your MCP settings.

Via Smithery

Use the Smithery CLI to install the server for Claude Desktop automatically:

npx -y @smithery/cli install mcp-graphql --client claude

Manual Installation

Add the following configuration to your Claude Desktop configuration file:

{
    "mcpServers": {
        "mcp-graphql": {
            "command": "npx",
            "args": ["mcp-graphql"],
            "env": {
                "ENDPOINT": "http://localhost:3000/graphql"
            }
        }
    }
}

Since version 1.0.0, mcp-graphql is configured using environment variables rather than command line arguments. Use these variables to define the target endpoint, authentication, and schema source.

Security Note: Mutations are disabled by default to prevent LLMs from modifying data. Set ALLOW_MUTATIONS=true only when necessary and with caution.

Below are common patterns for running the server with different configurations.

Basic usage with a local GraphQL server:

ENDPOINT=http://localhost:3000/graphql npx mcp-graphql

Using with custom headers (e.g., Authorization):

ENDPOINT=https://api.example.com/graphql HEADERS='{"Authorization":"Bearer token123"}' npx mcp-graphql

Enabling mutation operations:

ENDPOINT=http://localhost:3000/graphql ALLOW_MUTATIONS=true npx mcp-graphql

Using a local schema file instead of introspection:

ENDPOINT=http://localhost:3000/graphql SCHEMA=./schema.graphql npx mcp-graphql

Using a schema file hosted at a URL:

ENDPOINT=http://localhost:3000/graphql SCHEMA=https://example.com/schema.graphql npx mcp-graphql

The server exposes two primary tools for interacting with GraphQL APIs:

1. introspect-schema: Retrieves the GraphQL schema. This tool uses the provided SCHEMA environment variable (local path or URL) or performs an introspection query against the ENDPOINT. Use this if the schema is not already available as a resource.
2. query-graphql: Executes GraphQL queries against the configured ENDPOINT.
   • Note: Mutations are disabled by default. You must set ALLOW_MUTATIONS=true to enable them.

The mcp-graphql server is configured using environment variables. These settings determine the target GraphQL endpoint, authentication headers, and whether mutation operations are permitted.

The query-graphql tool executes a GraphQL operation against the configured ENDPOINT.

Arguments:

• query (string): The GraphQL query or mutation string.
• variables (string, optional): A JSON string containing the variables for the query.

Note on Mutations: If the ALLOW_MUTATIONS environment variable is not set to "true", any operation containing a mutation definition will return an error.

{
  "query": "query GetUser($id: ID!) { user(id: $id) { name } }",
  "variables": "{\"id\": \"123\"}"
}

Use introspectEndpoint to perform a GraphQL introspection query against a live endpoint. This function sends a POST request containing the standard introspection query and returns the resulting schema as a GraphQL Schema Definition Language (SDL) string. You can optionally provide custom headers (e.g., for authentication).

import { introspectEndpoint } from './src/helpers/introspection';

const sdl = await introspectEndpoint('https://api.example.com/graphql', {
  'Authorization': 'Bearer my-token'
});
console.log(sdl);

Use introspectSchemaFromUrl to retrieve a GraphQL schema (SDL) that is hosted at a specific URL. This is useful when your schema is served as a static file rather than through a live GraphQL endpoint.

import { introspectSchemaFromUrl } from './src/helpers/introspection';

const sdl = await introspectSchemaFromUrl('https://example.com/schema.graphql');
console.log(sdl);

The introspect-schema tool allows an LLM to retrieve the GraphQL schema definition. This is useful for understanding the available types, queries, and mutations before attempting to execute a query.

Arguments:

• __ignore__ (boolean, default: false): A dummy argument used to ensure compatibility with clients that struggle with empty argument objects.

Use introspectLocalSchema to read a GraphQL schema (SDL) from a file on your local filesystem. This is the preferred method when working with local development environments or checked-in schema files.

import { introspectLocalSchema } from './src/helpers/introspection';

const sdl = await introspectLocalSchema('./path/to/schema.graphql');
console.log(sdl);