openapi-to-mcp

Generate a fully working MCP (Model Context Protocol) server from any OpenAPI 3.x spec — JSON or YAML, local file or URL.

One command turns your REST API into an AI-ready MCP server with proper tool definitions, input validation, authentication, and error handling.

Install

npm install -g openapi-to-mcp
# or use without installing:
npx openapi-to-mcp ./petstore.yaml

Quick Start

# From a local file
npx openapi-to-mcp ./petstore.yaml --output ./petstore-mcp

# From a URL
npx openapi-to-mcp https://petstore3.swagger.io/api/v3/openapi.json -o ./petstore-mcp

# Preview tools without generating files
npx openapi-to-mcp ./petstore.yaml --list-tools

# Dry run (parse only, no output)
npx openapi-to-mcp ./petstore.yaml --dry-run

What Gets Generated

Given this input:

# petstore.yaml (OpenAPI 3.0)
openapi: "3.0.0"
info:
  title: Petstore
  version: "1.0.0"
servers:
  - url: https://petstore3.swagger.io/api/v3
paths:
  /pet/{petId}:
    get:
      operationId: getPetById
      summary: Find pet by ID
      parameters:
        - name: petId
          in: path
          required: true
          schema:
            type: integer

You get a ready-to-run MCP server:

petstore-mcp/
├── src/
│   └── server.ts      # MCP server with all tools
├── package.json
├── tsconfig.json
├── .env.example
└── README.md

Then:

cd petstore-mcp
npm install
npm run build
node dist/server.js

CLI Reference

openapi-to-mcp <spec> [options]

Arguments:
  spec                  Path or URL to an OpenAPI 3.x spec (JSON or YAML)

Options:
  -o, --output <dir>    Output directory (default: ./mcp-server)
  --dry-run             Parse and show info, do not write files
  --list-tools          Print all tools that would be generated, then exit
  -V, --version         Show version
  -h, --help            Show help

Authentication

openapi-to-mcp auto-detects auth from securitySchemes and generates the appropriate environment variable handling.

| Scheme | Detected as | Env var | Behaviour | |--------|------------|---------|-----------| | http + bearer | Bearer token | API_BEARER_TOKEN | Authorization: Bearer $TOKEN | | http + basic | Basic auth | API_BASIC_CREDENTIALS | Authorization: Basic $CREDS | | apiKey | API key | API_KEY | Header / query / cookie | | (none) | No auth | — | No auth header added |

The generated server exits with a clear error message if a required env var is missing.

Generated Server

The generated src/server.ts:

• Uses the official @modelcontextprotocol/sdk package
• Runs on stdio transport (standard for MCP)
• Creates one tool per API endpoint (named by operationId or derived from method + path)
• Validates inputs via MCP's built-in schema support
• Calls the real API with fetch, including auth
• Returns human-readable errors on HTTP failures
• Flattens JSON request body top-level properties into tool parameters for ergonomic use

OpenAPI Feature Support

| Feature | Support | |---------|---------| | OpenAPI 3.0.x | ✅ | | OpenAPI 3.1.x | ✅ | | YAML specs | ✅ | | JSON specs | ✅ | | Remote URL specs | ✅ | | Path parameters | ✅ | | Query parameters | ✅ | | Header parameters | ✅ | | Request body (JSON) | ✅ | | Bearer auth | ✅ | | API key auth | ✅ | | Basic auth | ✅ | | $ref resolution | ✅ (local refs) | | Deprecated endpoints | ✅ (annotated) | | Duplicate operationIds | ✅ (auto-suffixed) |

Using with Claude Desktop

Add the generated server to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "petstore": {
      "command": "node",
      "args": ["/absolute/path/to/petstore-mcp/dist/server.js"],
      "env": {
        "API_BEARER_TOKEN": "your-token-here"
      }
    }
  }
}

Using with Claude Code

claude mcp add petstore -- node /absolute/path/to/petstore-mcp/dist/server.js

With environment variables:

claude mcp add petstore \
  -e API_BEARER_TOKEN=your-token \
  -- node /absolute/path/to/petstore-mcp/dist/server.js

Example: GitHub API

npx openapi-to-mcp https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.yaml \
  --output ./github-mcp

cd github-mcp
npm install && npm run build
export API_BEARER_TOKEN=ghp_your_token
node dist/server.js

Recommended Models

When using your generated MCP server with Claude, these model IDs are confirmed compatible:

• claude-haiku-4.5 — fast, low-cost, great for simple API calls
• claude-sonnet-4-6 — balanced performance (recommended default)
• claude-opus-4-6 — most capable, best for complex multi-step API workflows

Contributing

Pull requests welcome. The core pipeline is:

1. src/parser.ts — loads and parses the OpenAPI spec into a clean domain model
2. src/generator.ts — maps the parsed spec to template data and writes files
3. src/templates.ts — Handlebars rendering helpers
4. templates/server.ts.hbs — the MCP server template
5. templates/package.json.hbs — generated project package.json template

License

MIT