Registry / llm-agents / openapi-mcp-generator

openapi-mcp-generator

library0.1.1jsnpmunverified

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.

llm-agents http-networking devops

npm install openapi-mcp-generator

github ↗package ↗

INSTALL

IMPORT

SIG · OPENAPI-MCP-GENERA

openapi-mcp-generator

llm-agentsjavascriptv0.1.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

generateServer

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

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

ESM-only since v3; CommonJS require not supported.

default

✓ import generateMCPServer from 'openapi-mcp-generator';

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

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

generateServer (CLI)

✓ npx openapi-mcp-generator --input spec.yaml --output ./server

✗ openapi-mcp-generator --help

The primary usage is via CLI. Programmatic API available but less documented; use the CLI for typical workflows.

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

openapi-mcp --version

Debug

Known issues

breakingESM-only since v3.0.0 – require() will throw an error.

fix

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

affects: >=3.0.0

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

fix

Upgrade Node.js to 20+.

affects: >=3.0.0

gotchaIf 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.

affects: >=1.0.0

gotchaThe 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.

affects: >=3.0.0

Errors

Common errors & fixes

Error: Cannot find module '@modelcontextprotocol/sdk'

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: Unable to parse OpenAPI specification. Ensure the file is valid JSON or YAML.

Invalid format or malformed spec file.

fix

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

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

OpenAPI spec lacks servers field or has empty list.

fix

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

Upgrade

Version history

0.1.1latest on npm

Audit

Dependencies

@modelcontextprotocol/sdkrequiredRequired to generate MCP server code using the protocol SDK

json-schema-to-zodrequiredConverts OpenAPI JSON schema definitions to Zod schemas for runtime validation

zodrequiredRuntime validation library used for input validation in generated server

Agent activity

20 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/harsha-iiiv/openapi-mcp-generator ↗

packagehttps://www.npmjs.com/package/openapi-mcp-generator ↗