openapi-to-mcp

Turn any OpenAPI spec into a ready-to-run MCP server in seconds.

mcp-gen generate --input openapi.yaml --lang typescript --out ./my-server

No boilerplate. No manual wiring. Just a working Model Context Protocol server with every endpoint mapped to a tool — in TypeScript or Python.

Why

MCP became the standard way to expose APIs to AI agents in 2025/26. Writing MCP servers by hand means repeating the same scaffolding for every project — parsing specs, registering tools, handling schemas. openapi-to-mcp eliminates that entirely.

You bring the spec. The CLI brings the server.

How it works

sequenceDiagram
    participant User
    participant CLI
    participant Parser
    participant Generator
    participant Output

    User->>CLI: mcp-gen generate --input api.yaml --lang python
    CLI->>Parser: validate & parse OpenAPI v3 (JSON or YAML)
    Parser->>Generator: internal AST (tools, models, examples)
    Generator->>Output: render Handlebars templates
    Output-->>User: TypeScript or Python MCP server project

Each path + method in your spec becomes an MCP tool with:

• Typed input schema derived from parameters and request body
• Example response from the spec pre-wired as a stub
• Incremental markers so re-generation never overwrites your custom logic

Requirements

• Node.js 20+
• npm 9+

Installation

git clone https://github.com/your-username/openapi-to-mcp.git
cd openapi-to-mcp
npm install
npm run build

npm publish coming soon — npm install -g mcp-gen will work once released.

Usage

Validate a spec

Accepts .json, .yaml, .yml, or a URL.

node dist/cli/index.js validate --input ./api/openapi.yaml

✔ Spec is valid

  Tools: 12  Models: 6  Base URL: https://api.example.com

Generate a TypeScript server

node dist/cli/index.js generate \
  --input ./api/openapi.yaml \
  --lang typescript \
  --out ./my-server

✔ Generation complete

  ✓ 7 files created

    my-server/src/server.ts
    my-server/src/models.ts
    my-server/package.json
    my-server/tsconfig.json
    my-server/README.md
    my-server/Dockerfile
    my-server/.github/workflows/ci.yml

Generate a Python server

node dist/cli/index.js generate \
  --input ./api/openapi.yaml \
  --lang python \
  --out ./my-server

✔ Generation complete

  ✓ 6 files created

    my-server/server.py
    my-server/models.py
    my-server/requirements.txt
    my-server/Dockerfile
    my-server/README.md
    my-server/.github/workflows/ci.yml

Re-generate without losing your code (incremental)

node dist/cli/index.js generate \
  --input ./api/openapi.yaml \
  --out ./my-server \
  --incremental

✔ Generation complete

  ✓ 7 files created
  ↺ 3 handler(s) preserved

    ↺ get_users
    ↺ post_users
    ↺ get_users_id

Custom code between @@mcp-gen markers is preserved. Generated stubs are refreshed. Your logic is never touched.

Accepts URLs too

node dist/cli/index.js generate \
  --input https://petstore3.swagger.io/api/v3/openapi.json \
  --out ./petstore-mcp

CLI Reference

Generated project structure

TypeScript:

my-server/
├── src/
│   ├── server.ts        # MCP server — tool definitions + handlers
│   └── models.ts        # TypeScript interfaces from OpenAPI schemas
├── .github/
│   └── workflows/
│       └── ci.yml
├── Dockerfile
├── package.json
├── tsconfig.json
└── README.md

Python:

my-server/
├── server.py            # FastMCP server — tool definitions + handlers
├── models.py            # Pydantic models from OpenAPI schemas
├── requirements.txt
├── .github/
│   └── workflows/
│       └── ci.yml
├── Dockerfile
└── README.md

Connect to Claude Desktop

TypeScript:

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/absolute/path/to/my-server/dist/server.js"]
    }
  }
}

Python:

{
  "mcpServers": {
    "my-server": {
      "command": "python",
      "args": ["/absolute/path/to/my-server/server.py"]
    }
  }
}

Restart Claude Desktop. Your API tools appear automatically.

Implement handlers

Generated files return spec examples by default. Replace stubs with real logic.

TypeScript (src/server.ts):

case "get_users_id": {
  // @@mcp-gen:start:get_users_id
  const user = await db.users.findById(args.id);
  return { content: [{ type: "text", text: JSON.stringify(user) }] };
  // @@mcp-gen:end:get_users_id
}

Python (server.py):

@mcp.tool()
async def get_users_id(id: float) -> Any:
    # @@mcp-gen:start:get_users_id
    user = await db.users.find_by_id(id)
    return user
    # @@mcp-gen:end:get_users_id

Code between @@mcp-gen:start and @@mcp-gen:end markers is preserved when you re-run generate --incremental.

Development

npm test
npx tsc --noEmit

# TypeScript example
node dist/cli/index.js generate --input examples/petstore.json --out /tmp/ts-test --force

# Python example
node dist/cli/index.js generate --input examples/petstore.yaml --lang python --out /tmp/py-test --force

# Incremental example
node dist/cli/index.js generate --input examples/petstore.json --out /tmp/ts-test --incremental

Roadmap

Known limitations

• OpenAPI v2 (Swagger) is not supported — v3.x only
• oneOf / anyOf / discriminator schemas are partially handled
• copy-templates script uses cp — on Windows, change to xcopy in package.json

License

MIT © 2026