graphql2mcp

CLI Reference

The graphql2mcp CLI converts a GraphQL endpoint or schema file into a standalone MCP server.

The graphql2mcp CLI converts a GraphQL endpoint or schema file into a standalone MCP server.

Installation

npm install -g graphql2mcp

Or run without installing:

npx graphql2mcp <source>

Usage

graphql2mcp <source> [options]

The <source> argument can be:

  • A URL (https://api.example.com/graphql) -- introspects the endpoint
  • An SDL file path (./schema.graphql or ./schema.gql)
  • A glob pattern (./schemas/*.graphql) -- merges matched files
  • An introspection JSON file (./introspection.json)

Options

FlagAliasTypeDefaultDescription
--transport <type>-tstdio | httpstdioMCP transport type
--port <number>-pnumber3000HTTP port (when transport is http)
--mutations <mode>-mall | none | whitelistnoneMutation exposure mode
--mutation-whitelist <names>string[]Comma-separated mutation names to whitelist
--header <header>-Hstring[]HTTP header (e.g., "Authorization: Bearer x"), repeatable
--endpoint <url>-estringGraphQL execution endpoint
--name <name>-nstringgraphql-mcp-serverMCP server name
--depth <number>-dnumber3Field selection depth for return types
--include <names>string[]Only include these operation names (comma-separated)
--exclude <names>string[]Exclude these operation names (comma-separated)
--version-VShow version number
--help-hShow help

List flags (--include, --exclude, --mutation-whitelist) take comma-separated names, such as --include users,user. You can also repeat the flag (--include users --include user). Space-separated names (--include users user) are rejected with error: too many arguments.

Examples

Basic URL introspection

Introspect a public GraphQL API and expose all queries as MCP tools over Streamable HTTP:

graphql2mcp https://countries.trevorblades.com/graphql -t http

SDL file with execution endpoint

Load the schema from a local file and execute queries against a different endpoint:

graphql2mcp ./schema.graphql -e https://api.example.com/graphql

With authentication headers

Pass an authorization header for both introspection and runtime execution:

graphql2mcp https://api.example.com/graphql \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Multiple headers are supported:

graphql2mcp https://api.example.com/graphql \
  -H "Authorization: Bearer token123" \
  -H "X-API-Key: key456"

Enabling mutations

Expose all mutations:

graphql2mcp https://api.example.com/graphql -m all

Expose specific mutations by name:

graphql2mcp https://api.example.com/graphql \
  -m whitelist \
  --mutation-whitelist createUser,updateUser

See the Mutations guide for details on mutation modes and tool annotations.

Filtering operations

Only include specific operations:

graphql2mcp https://api.example.com/graphql \
  --include users,user,searchUsers

Exclude specific operations:

graphql2mcp https://api.example.com/graphql \
  --exclude internalMetrics,debugQuery

--include applies to mutations as well as queries. If you combine it with whitelisted mutations, list those mutations in --include too:

graphql2mcp https://api.example.com/graphql \
  --include users,user,createUser \
  -m whitelist --mutation-whitelist createUser

Glob pattern

Merge multiple schema files into a single MCP server:

graphql2mcp './schemas/*.graphql' -e https://api.example.com/graphql

Introspection JSON file

Load a schema from a saved introspection result:

graphql2mcp ./introspection.json -e https://api.example.com/graphql

Transport Options

http (Streamable HTTP)

The server starts an HTTP server using the MCP Streamable HTTP transport. This is the recommended transport for most use cases — remote clients, web-based agents, debugging, and production deployments.

graphql2mcp https://api.example.com/graphql -t http -p 3000

stdio

The server communicates over stdin/stdout using the MCP stdio transport. Use this for desktop MCP clients like Claude Desktop and Cursor that launch the server as a subprocess.

Example Claude Desktop configuration (claude_desktop_config.json):

{
    "mcpServers": {
        "my-graphql-api": {
            "command": "npx",
            "args": ["graphql2mcp", "https://api.example.com/graphql", "-H", "Authorization: Bearer token123"]
        }
    }
}

Execution Endpoint

When the source is a URL, the same URL is used for both schema introspection and runtime query execution by default.

When the source is a file, glob, or SDL string, you must specify the execution endpoint with --endpoint (-e). This is the URL where GraphQL queries will be sent at runtime.

You can also use --endpoint to override the execution URL when the introspection and execution endpoints differ:

graphql2mcp https://admin.example.com/graphql \
  -e https://api.example.com/graphql

On this page