OpenAPI → MCP Server

Standalone CLI for diagnosing, diffing, generating, running, and testing Node.js/TypeScript MCP servers from OpenAPI specifications.

Install

Install openapi-to-mcp-cli from PyPI. Requires Python 3.14+; building and running generated servers also requires Node.js 22+ and npm.

uv tool install openapi-to-mcp-cli
openapi-to-mcp --help

The installed command remains openapi-to-mcp. For one-off use:

uvx --from openapi-to-mcp-cli openapi-to-mcp --help

See the installation guide for upgrades, tagged Git installs, and release artifacts.

Quickstart

Generate a reusable project:

openapi-to-mcp generate \
  --openapi-json ./openapi.yaml \
  --output-dir ./generated-server

Run directly from a spec:

openapi-to-mcp run \
  --openapi-json https://petstore3.swagger.io/api/v3/openapi.json \
  --target-api-base-url https://petstore3.swagger.io/api/v3

Smoke-test a running server:

openapi-to-mcp test-server \
  --transport streamable-http \
  --host 127.0.0.1 \
  --port 8080 \
  --mcp-endpoint /mcp \
  --list-tools

Documentation

Public product documentation lives on GitHub Pages:

• Docs home: nihal1294.github.io/openapi-to-mcp

Current capabilities

• stdio and streamable-http generation targets
• spec-readiness diagnostics with doctor
• MCP-surface comparison with diff
• repeatable generation policy with mcpgen.yaml
• regeneration-safe custom tools via src/custom/tools.ts
• richer generated tool descriptions and input examples from spec metadata
• optional grouped tool names with first-tag prefixes
• optional request-scoped tool allowlists for streamable-http callers
• optional redacted audit logs for request and response payloads
• optional retry budgets and circuit breakers for safe upstream calls
• reviewable performance presets built on top of the explicit runtime controls
• strict mode by default with generation_report.json
• generated auth env mapping for apiKey, bearer, OAuth2, and OpenID Connect
• generated runtime controls for concurrency, queueing, timeout, bounded caching, rate limiting, retries, and circuit breakers
• generated-server E2E coverage against a local mock API
• CLI E2E coverage for generate, run, and test-server
• version-aware PyPI and GitHub Releases automation on master

Swagger 2 support

Swagger 2 response-only operations and base URL fields are supported. Convert operations that use Swagger 2 body or form parameters, top-level parameter types, security definitions, or unsupported protocol overrides to OpenAPI 3 before generating. Run openapi-to-mcp doctor to identify the affected operation and field.

Development

For repository-local workflows, use the repo docs directly:

• source and local workflows: Local Workflows
• contribution guide: Contributing

License

Apache License 2.0. See LICENSE.