openapi-mcp-generator weekly downloads statistics

OpenAPI to MCP Generator (openapi-mcp-generator)

Generate Model Context Protocol (MCP) servers from OpenAPI specifications.

This CLI tool automates the generation of MCP-compatible servers that proxy requests to existing REST APIs—enabling AI agents and other MCP clients to seamlessly interact with your APIs using your choice of transport methods.

✨ Features

• 🔧 OpenAPI 3.0 Support: Converts any OpenAPI 3.0+ spec into an MCP-compatible server. • 🔁 Proxy Behavior: Proxies calls to your original REST API while validating request structure and security. • 🔐 Authentication Support: API keys, Bearer tokens, Basic auth, and OAuth2 supported via environment variables. • 🧪 Zod Validation: Automatically generates Zod schemas from OpenAPI definitions for runtime input validation. • ⚙️ Typed Server: Fully typed, maintainable TypeScript code output. • 🔌 Multiple Transports: Communicate over stdio, SSE via Hono, or StreamableHTTP. • 🧰 Project Scaffold: Generates a complete Node.js project with tsconfig.json, package.json, and entry point. • 🧪 Built-in HTML Test Clients: Test API interactions visually in your browser (for web-based transports).

🚀 Installation

You can also use yarn global add openapi-mcp-generator or pnpm add -g openapi-mcp-generator

🛠 Usage

CLI Options

| Option | Alias | Description | Default |

| --input | -i | Path or URL to OpenAPI specification (YAML or JSON) | Required | | --output | -o | Directory to output the generated MCP project | Required | | --server-name | -n | Name of the MCP server (package.json:name) | OpenAPI title or mcp-api-server | | --server-version | -v | Version of the MCP server (package.json:version) | OpenAPI version or 1.0.0 | | --base-url | -b | Base URL for API requests. Required if OpenAPI servers missing or ambiguous. | Auto-detected if possible | | --transport | -t | Transport mode: "stdio" (default), "web", "streamable-http", or "cloudflare-worker" | "stdio" | | --port | -p | Port for web-based transports | 3000 | | --default-include | | Default behavior for x-mcp filtering. Accepts true or false (case-insensitive). true = include by default, false = exclude by default. | true | | --allow-external-refs | | Allow resolving external http(s) $ref references in the spec. Disabled by default to prevent SSRF during parsing. | false | | --max-tool-name-length | | Maximum length for generated tool names (Claude Desktop caps at 64). Longer names are truncated with a hash suffix. | 64 | | --header-passthrough | | Comma-separated inbound header names to forward to the upstream API (web/streamable-http). Enables per-user API keys via MCP client headers. | _(none)_ | | --insecure | -k | Allow insecure HTTPS connections (skip TLS certificate verification) in the generated server. | false | | --generate-lib | | Generate library-style output: export main() instead of auto-invoking it, omitting signal/cleanup wiring. | false | | --custom-auth | | Generate an editable src/auth.ts hook (applyCustomAuth) called before built-in auth; return true to skip built-in auth. | false | | --oauth-creds-in-body | | Send OAuth2 client credentials in the token request body instead of the Basic Authorization header. | false | | --force | | Overwrite existing files in the output directory without confirmation | false |

Configuring the API base URL at runtime: the generated server reads API_BASE_URL from the environment (.env), overriding the value baked in from the OpenAPI servers list. The port resolves from --port, then the PORT env var, then 3000.

📦 Programmatic API

You can also use this package programmatically in your Node.js applications:

For full documentation of the programmatic API, see PROGRAMMATIC_API.md.

🧱 Project Structure

The generated project includes:

Core dependencies:

• @modelcontextprotocol/sdk - MCP protocol implementation • axios - HTTP client for API requests • zod - Runtime validation • json-schema-to-zod - Convert JSON Schema to Zod • Transport-specific deps (Hono, uuid, etc.)

📡 Transport Modes

Stdio (Default)

Communicates with MCP clients via standard input/output. Ideal for local development or integration with LLM tools.

Web Server with SSE

Launches a fully functional HTTP server with:

• Server-Sent Events (SSE) for bidirectional messaging • REST endpoint for client → server communication • In-browser test client UI • Multi-connection support • Built with lightweight Hono framework

StreamableHTTP

Implements the MCP StreamableHTTP transport which offers:

• Stateful JSON-RPC over HTTP POST requests • Session management using HTTP headers • Proper HTTP response status codes • Built-in error handling • Compatibility with MCP StreamableHTTPClientTransport • In-browser test client UI • Built with lightweight Hono framework

Cloudflare Worker

Generates a complete, deployable Cloudflare Workers project that serves the MCP server over Streamable HTTP at /mcp using the MCP SDK's WebStandardStreamableHTTPServerTransport directly (no extra framework dependency). Deploy it to your own Cloudflare account with one command:

Highlights:

• Stateless, runs on the free Workers tier (no Durable Objects or KV). A fresh MCP server + transport is created per request (required by MCP SDK ≥ 1.26). • Lean dependencies: just @modelcontextprotocol/sdk and zod — no extra agent framework. • Non-secret config (e.g. API_BASE_URL) lives in wrangler.jsonc under vars; secrets are set with wrangler secret put and read from the env binding — never committed. • Workers-native runtime: global fetch (no Node https), and argument validation uses build-time-emitted zod (no runtime eval). • Auth is scheme-aware: API key (header/query/cookie), HTTP basic/bearer, and OAuth2 client-credentials are derived from env secrets. • --header-passthrough, --custom-auth, --port, --insecure, --generate-lib, and --oauth-creds-in-body do not apply to this target and are ignored with a warning.…

Description from the npm listing.