graphql2mcp

This guide walks you through installing graphql2mcp and converting your first GraphQL schema into an MCP server.

Installation

Library (integrate into existing MCP server)

npm install @graphql2mcp/lib

CLI Proxy (standalone server)

Run directly with npx (no install needed):

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

Or install globally:

npm install -g graphql2mcp

Your First MCP Server

From Code

If you have an existing MCP server and want to add GraphQL tools alongside your own:

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 GraphQL tools from a schema
const result = registerGraphQLTools(server, {
    source: './schema.graphql',
    endpoint: 'https://api.example.com/graphql'
});

console.error(`Registered ${result.count} tools`);

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

From a URL

Point at a GraphQL endpoint. The CLI will introspect the schema and start an MCP server:

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

This creates MCP tools for every query in the schema and starts a Streamable HTTP server on port 3000, ready for any MCP client.

For desktop MCP clients like Claude Desktop or Cursor that expect stdio transport:

npx graphql2mcp https://countries.trevorblades.com/graphql

From an SDL File

If you have a local .graphql schema file, provide a file path and an execution endpoint:

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

Here is an example schema.graphql:

type Query {
    "Get a user by ID"
    user(id: ID!): User
    "List all users with optional pagination"
    users(limit: Int, offset: Int): [User!]!
}

type User {
    id: ID!
    name: String!
    email: String!
    role: Role!
}

enum Role {
    ADMIN
    USER
    MODERATOR
}

The CLI generates MCP tools named query_user and query_users, each with a Zod input schema matching the GraphQL arguments.

What's Next

Library Mode -- integrate into existing MCP servers
CLI Reference -- all flags, options, and usage patterns
Mutations -- configure which mutations are exposed as tools
Architecture -- how GraphQL schemas become MCP tools

Getting Started