mcpgen

Turn any API into an AI agent tool. One command.

Point at an OpenAPI spec. Get a working MCP server in 10 seconds.
Your AI agent can now call Stripe, GitHub, Slack, Notion — or any API with a spec.

Quick Start • Registry • How It Works • Examples • Contributing

The Problem

You want your AI agent to call an API. Today you have to:

1. Find or build an MCP server for that specific API
2. Write tool definitions, parameter schemas, auth handling
3. Test it, debug it, deploy it
4. Repeat for every new API

mcpgen does all of this in one command.

Quick Start

# Try it right now with the demo Petstore API (no auth needed)
npx mcpgen serve https://petstore3.swagger.io/api/v3/openapi.json

That's it. Your AI agent now has 19 tools for managing pets, orders, and users.

Add a real API

# Add Stripe to your Claude Code config
npx mcpgen add stripe

# Or point at any OpenAPI spec
npx mcpgen serve https://api.example.com/openapi.json --bearer-token $MY_TOKEN

Inspect before serving

# See what tools would be generated
npx mcpgen inspect https://petstore3.swagger.io/api/v3/openapi.json

  Swagger Petstore v1.0.27

  19 Tools:

  addPet                    POST    /pet              (1 params)
  updatePet                 PUT     /pet              (1 params)
  findPetsByStatus          GET     /pet/findByStatus (1 params)
  getPetById                GET     /pet/{petId}      (1 params)
  getInventory              GET     /store/inventory  (0 params)
  placeOrder                POST    /store/order      (1 params)
  createUser                POST    /user             (1 params)
  ...

Registry

mcpgen ships with pre-built configs for popular APIs. One command to add them:

| API | Command | What You Get | |-----|---------|-------------| | GitHub | mcpgen add github | Repos, issues, PRs, actions, users | | Stripe | mcpgen add stripe | Payments, subscriptions, invoices | | Slack | mcpgen add slack | Messages, channels, users, reactions | | Notion | mcpgen add notion | Pages, databases, blocks, search | | Linear | mcpgen add linear | Issues, projects, teams, cycles | | OpenAI | mcpgen add openai | Completions, embeddings, images | | Petstore | mcpgen add petstore | Demo API for testing |

# List all available APIs
mcpgen list

# Search by keyword
mcpgen search payments

Want to add an API? See Contributing.

How It Works

                    +-----------------+
  OpenAPI Spec ---> |     mcpgen      | ---> MCP Server (stdio)
  (URL or file)     |                 |      ready for Claude Code,
                    | 1. Parse spec   |      Cursor, or any MCP client
                    | 2. Build tools  |
                    | 3. Handle auth  |
                    +-----------------+

1. Parse — Reads any OpenAPI 3.0/3.1 spec (JSON or YAML, URL or file). Resolves $refs, extracts endpoints, parameters, and auth schemes.

2. Build Tools — Each API endpoint becomes an MCP tool with:

   • A human-readable name (from operationId)
   • A clear description (from summary + description)
   • A typed input schema (from parameters + request body)
   • Proper parameter handling (path, query, header, body)

3. Serve — Starts a stdio MCP server that proxies tool calls to the real API with proper auth, headers, and error formatting.

Examples

Use with Claude Code

Add to your .mcp.json:

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": ["mcpgen", "serve", "https://api.example.com/openapi.json"],
      "env": {
        "API_TOKEN": "your-token-here"
      }
    }
  }
}

Or use the add command to auto-configure:

mcpgen add github
# Adds to .mcp.json automatically

Use with a local spec file

mcpgen serve ./my-api-spec.yaml --base-url https://localhost:3000

Use programmatically

import { parseSpec, createMcpServer } from "mcpgen";

const spec = await parseSpec("https://api.example.com/openapi.json");
const server = createMcpServer(spec, {
  baseUrl: "https://api.example.com",
  auth: { type: "bearer", value: process.env.API_TOKEN },
});

Auth

mcpgen supports three auth methods, auto-detected from the OpenAPI spec:

| Method | Env Variables | Flag | |--------|--------------|------| | Bearer Token | API_TOKEN, BEARER_TOKEN, AUTH_TOKEN | --bearer-token | | API Key | API_KEY, or derived from scheme name | --api-key | | Basic Auth | API_USER + API_PASSWORD | — |

Registry entries specify which env var to use (e.g., GITHUB_TOKEN for GitHub).

CLI Reference

mcpgen serve <spec>       Start MCP server from OpenAPI spec
  --base-url <url>        Override base URL
  --api-key <key>         API key auth
  --bearer-token <token>  Bearer token auth

mcpgen inspect <spec>     Preview tools without starting server

mcpgen add <name>         Add registry API to .mcp.json
  --config <path>         Config file path (default: .mcp.json)

mcpgen list               List all registry APIs
mcpgen search <query>     Search registry
mcpgen --version          Show version
mcpgen --help             Show help

Contributing

Add an API to the registry

1. Create a YAML file in registry/:

name: my-api
displayName: My API
description: What this API does
specUrl: https://example.com/openapi.json
baseUrl: https://api.example.com
authType: bearer
authEnvVar: MY_API_KEY
tags:
  - category
  - keywords

2. Submit a PR. That's it.

Development

git clone https://github.com/your-username/mcpgen.git
cd mcpgen
npm install
npm run build
npm test

# Test locally
node dist/cli.js inspect https://petstore3.swagger.io/api/v3/openapi.json

License

MIT