graphql2mcp

Convert GraphQL schemas and endpoints into Model Context Protocol (MCP) servers. Point at any GraphQL API and get an MCP server with tools mapped from queries and mutations.

Features

• Library mode — add GraphQL-backed tools to your existing TypeScript MCP server with one function call
• Zero config proxy — pass a GraphQL endpoint URL and get an MCP server with every query as a tool
• Mutation control — expose all mutations, none, or an explicit whitelist
• MCP tool annotations — queries get readOnlyHint: true, mutations get destructiveHint: true
• Multiple schema sources — SDL files, globs, introspection JSON, inline SDL strings, or live URL introspection
• Multi-endpoint — combine multiple GraphQL APIs into a single MCP server with prefix-based namespacing
• Include/exclude filters — cherry-pick which operations become tools
• ESM only — modern, tree-shakeable, with complete TypeScript types

Quick Start

Library Mode

Add GraphQL tools to an existing MCP server:

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
import { registerGraphQLTools } from '@graphql2mcp/lib';

const server = new McpServer({ name: 'my-server', version: '1.0.0' });

// Register your own tools alongside GraphQL tools
registerGraphQLTools(server, {
    source: 'schema.graphql',
    endpoint: 'https://api.example.com/graphql'
});

const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
await server.connect(transport);

Or use getGraphQLTools for full control over registration:

import { getGraphQLTools } from '@graphql2mcp/lib';

const { tools } = getGraphQLTools({
    source: 'schema.graphql',
    endpoint: 'https://api.example.com/graphql'
});

for (const tool of tools) {
    server.registerTool(
        tool.name,
        {
            title: tool.title,
            description: tool.description,
            inputSchema: tool.inputSchema,
            annotations: tool.annotations
        },
        tool.handler
    );
}

Proxy Mode

Run against a live GraphQL endpoint (introspects the schema automatically):

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

This starts a Streamable HTTP MCP server on port 3000. For stdio transport (used by Claude Desktop, Cursor), omit the -t http flag:

npx graphql2mcp https://api.example.com/graphql

Or from a local SDL file:

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

Packages

This is a monorepo managed with pnpm workspaces:

How It Works

flowchart TD
    subgraph Input
        A[SDL File] --> L
        B[Inline SDL] --> L
        C[Introspection JSON] --> L
        D[Glob Pattern] --> L
        E[Live URL] --> U
    end

    L[loadSchema] --> S[GraphQLSchema]
    U[loadSchemaFromUrl] --> S

    subgraph "@graphql2mcp/core"
        S --> G[generateTools]
        G --> T[ToolDefinition]
    end

    subgraph MCP Server
        T --> R[registerTool]
        R --> Q[Tool Called]
    end

    Q -->|POST query + variables| EP[GraphQL Endpoint]
    EP -->|JSON response| Q

1. Load — read a GraphQL schema from an SDL file (or glob of multiple files), introspection JSON, inline SDL string, or live URL introspection
2. Parse — build a GraphQLSchema object using the graphql library
3. Generate — walk every Query and Mutation field, mapping arguments to Zod schemas, building field selections, and producing ToolDefinition objects with names, descriptions, annotations, and pre-built query documents
4. Register — add each tool to an McpServer. When an AI agent calls a tool, the server executes the corresponding GraphQL operation against the endpoint and returns the result as JSON

Runtime Compatibility

Development

pnpm install
pnpm build
pnpm test

License

MIT