# Graphql2mcp

> Convert any GraphQL API into an MCP server. CLI proxy or library mode.

- **Type:** MCP server
- **Install:** `agentstack add mcp-kkonstantinov-graphql2mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [KKonstantinov](https://agentstack.voostack.com/s/kkonstantinov)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [KKonstantinov](https://github.com/KKonstantinov)
- **Source:** https://github.com/KKonstantinov/graphql2mcp
- **Website:** https://graphql2mcp.vercel.app

## Install

```sh
agentstack add mcp-kkonstantinov-graphql2mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# graphql2mcp

[](https://www.npmjs.com/package/graphql2mcp) [](https://www.npmjs.com/package/graphql2mcp)
[](https://www.typescriptlang.org/) [](https://github.com/KKonstantinov/graphql2mcp/blob/main/LICENSE)
[](https://graphql2mcp.vercel.app/docs)

Convert GraphQL schemas and endpoints into [Model Context Protocol](https://modelcontextprotocol.io/) (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:

```typescript
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:

```typescript
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):

```bash
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:

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

Or from a local SDL file:

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

## Packages

This is a monorepo managed with [pnpm workspaces](https://pnpm.io/workspaces):

| Package                               | Description                                                                             |
| ------------------------------------- | --------------------------------------------------------------------------------------- |
| [`@graphql2mcp/lib`](packages/lib/)   | Library for integrating into existing TypeScript MCP servers                            |
| [`@graphql2mcp/core`](packages/core/) | Shared engine — schema loading, tool generation, execution, and MCP server registration |
| [`graphql2mcp`](packages/proxy/)      | Standalone CLI proxy — point at a GraphQL endpoint, get an MCP server                   |

## How It Works

```mermaid
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

| Runtime | Version | Status |
| ------- | ------- | ------ |
| Node.js | >= 22   | Tested |
| Bun     | >= 1.2  | Tested |
| Deno    | >= 2.0  | Tested |

## Development

```bash
pnpm install
pnpm build
pnpm test
```

## License

MIT

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [KKonstantinov](https://github.com/KKonstantinov)
- **Source:** [KKonstantinov/graphql2mcp](https://github.com/KKonstantinov/graphql2mcp)
- **License:** MIT
- **Homepage:** https://graphql2mcp.vercel.app

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-kkonstantinov-graphql2mcp
- Seller: https://agentstack.voostack.com/s/kkonstantinov
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.