OpenAPI MCP Generator

3.3.0 verified Sat Apr 25 auth: no javascript

CLI tool that generates Model Context Protocol (MCP) server code from OpenAPI 3.0+ specifications. v3.3.0 released March 2025. Generates a complete, typed TypeScript project with Zod validation, proxy behavior to the original REST API, and support for multiple transports (stdio, SSE via Hono, StreamableHTTP). Key differentiators: automates full scaffolding including package.json, tsconfig.json, and entry point; built-in HTML test clients for web transports; supports API key, Bearer, Basic, and OAuth2 auth via environment variables. Requires Node >=20 and peer deps @modelcontextprotocol/sdk, json-schema-to-zod, zod. Ships TypeScript types.

Common errors

error Error: Cannot find module '@modelcontextprotocol/sdk' ↓

cause Missing or mismatched peer dependency.

fix

Run npm install in the generated output directory or globally install the peer dep: npm install @modelcontextprotocol/sdk

error Error: Unable to parse OpenAPI specification. Ensure the file is valid JSON or YAML. ↓

cause Invalid format or malformed spec file.

fix

Validate your spec with a linter (e.g., npx @apidevtools/swagger-cli validate).

error Error: servers array is empty or missing. Provide --base-url option. ↓

cause OpenAPI spec lacks servers field or has empty list.

fix

Add a --base-url URL argument to the CLI command.

Warnings

breaking ESM-only since v3.0.0 – require() will throw an error. ↓

fix Use import syntax or switch to CommonJS via dynamic import().

deprecated Node.js <20 support dropped. Use Node 20+ or older versions of the package. ↓

fix Upgrade Node.js to 20+.

gotcha If your OpenAPI spec uses relative file references ($ref), they may not resolve correctly. Always provide a fully dereferenced spec or a single file. ↓

fix Use a tool like swagger-cli bundle --dereference to produce a single, self-contained spec before generating.

gotcha The generated server uses Zod schemas for validation; ensure your OpenAPI schema adheres to JSON Schema draft-07 or later for best compatibility. ↓

fix If validation fails, check the Zod error messages; you may need to adjust your OpenAPI spec.

Install

npm install openapi-mcp-generator

yarn add openapi-mcp-generator

pnpm add openapi-mcp-generator

Imports

generateServer

wrong

const generateServer = require('openapi-mcp-generator');

correct

import { generateServer } from 'openapi-mcp-generator';

ESM-only since v3; CommonJS require not supported.

default

wrong

import { default as generateMCPServer } from 'openapi-mcp-generator';

correct

import generateMCPServer from 'openapi-mcp-generator';

The package also exports a default function (same as generateServer) for convenience.

generateServer (CLI)
wrong
```
openapi-mcp-generator --help
```
correct
```
npx openapi-mcp-generator --input spec.yaml --output ./server
```
The primary usage is via CLI. Programmatic API available but less documented; use the CLI for typical workflows.

Quickstart

Shows how to generate a stdio MCP server from an OpenAPI specification using the CLI, then run it.

// Install globally or use npx
// Generate a stdio-based MCP server from a local OpenAPI file
// Command:
npx openapi-mcp-generator --input petstore.yaml --output ./mcp-server --server-name petstore-api --server-version 1.0.0

// Then run the generated server:
cd ./mcp-server
npm start