OpenAPI → MCP Server

What is OpenAPI → MCP Server?

A Python CLI tool that generates a Node.js/TypeScript Model Context Protocol (MCP) server from an OpenAPI v3 specification (JSON or YAML). Each API operation becomes an MCP tool, and the generated server translates MCP calls into HTTP requests to the target API.

How to use OpenAPI → MCP Server?

Install dependencies via poetry install --no-dev, then run the generate command with --openapi-json pointing to the spec file or URL. After generation, set the .env file with the target API base URL (and optional auth header), then npm install, npm run build, and npm start inside the output directory. Use the test-server command or the MCP Inspector to test the server.

Key features of OpenAPI → MCP Server

• Parses OpenAPI v3 JSON or YAML from local files or URLs.
• Maps each API operation (GET, POST, PUT, DELETE, PATCH) to an MCP tool.
• Generates a runnable Node.js/TypeScript MCP server project.
• Supports stdio and SSE transport with configurable port.
• Includes basic error mapping from HTTP status codes to MCP errors.
• Handles simple local $refs, cycles, and basic type schemas.

Use cases of OpenAPI → MCP Server

• Quickly turn any REST API with an OpenAPI spec into an MCP-compatible server.
• Enable AI assistants to call existing APIs via MCP without manual tool definitions.
• Prototype MCP integrations for legacy or third-party HTTP APIs.

FAQ from OpenAPI → MCP Server

What are the prerequisites to run the generator?

Python 3.12+, Poetry, and Node.js 20+ for the generated server. The MCP SDK (1.5.0) is installed automatically via Poetry.

What transport options does the generated server support?

The generated server can use stdio (default) or SSE. For SSE, specify --transport sse and optionally --port (default 8080).

How do I provide authentication for the target API?

Set the TARGET_API_AUTH_HEADER environment variable in the .env file (e.g., Authorization: Bearer token or X-API-Key: key).

Where is the generated server code placed?

By default in ./mcp-server, but you can change this with --output-dir. The generated directory includes a complete Node.js/TypeScript project with its own README.

Can I test the generated server without a full client?

Yes, the tool includes a test-server command to send ListTools and CallTool requests via stdio or SSE. Alternatively, use the MCP Inspector for a graphical interface.