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
``bash npm install -g openapi-mcp-generator `
> You can also use yarn global add openapi-mcp-generator or pnpm add -g openapi-mcp-generator
--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", or "streamable-http" | "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 | | --force | | Overwrite existing files in the output directory without confirmation | false |
📦 Programmatic API
You can also use this package programmatically in your Node.js applications:
`javascript import { getToolsFromOpenApi } from 'openapi-mcp-generator';
// Extract MCP tool definitions from an OpenAPI spec const tools = await getToolsFromOpenApi('./petstore.json');
Communicates with MCP clients via standard input/output. Ideal for local development or integration with LLM tools.
$3
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
$3
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
$3
| Feature | stdio | web (SSE) | streamable-http | | ------------------ | ------------------- | ----------------- | ------------------ | | Protocol | JSON-RPC over stdio | JSON-RPC over SSE | JSON-RPC over HTTP | | Connection | Persistent | Persistent | Request/response | | Bidirectional | Yes | Yes | Yes (stateful) | | Multiple clients | No | Yes | Yes | | Browser compatible | No | Yes | Yes | | Firewall friendly | No | Yes | Yes | | Load balancing | No | Limited | Yes | | Status codes | No | Limited | Full HTTP codes | | Headers | No | Limited | Full HTTP headers | | Test client | No | Yes | Yes |
---
🔐 Environment Variables for Authentication
Configure auth credentials in your environment:
| Auth Type | Variable Format | | ---------- | -------------------------------------------------------------------------------------------------- | | API Key |
You can control which operations are exposed as MCP tools using a vendor extension flag
x-mcp. This extension is supported at the root, path, and operation levels. By default, endpoints are included unless explicitly excluded.
- Extension:
x-mcp: true | false - Default: true (include by default) - Precedence: operation > path > root (first non-undefined wins) - CLI option: --default-include false to change default to exclude by default
Examples:
`yaml
Optional root-level default
x-mcp: true
paths: /pets: x-mcp: false # exclude all ops under /pets get: x-mcp: true # include this operation anyway
/users/{id}: get: # no x-mcp -> included by default
`
This uses standard OpenAPI extensions (x-… fields). See the OpenAPI Extensions guide for details.
Note:
x-mcp must be a boolean or the strings "true"/"false" (case-insensitive). Other values are ignored in favor of higher-precedence or default behavior.
---
▶️ Running the Generated Server
`bash cd path/to/output/dir npm install
Run in stdio mode
npm start
Run in web server mode
npm run start:web
Run in StreamableHTTP mode
npm run start:http `
$3
For web and StreamableHTTP transports, a browser-based test client is automatically generated:
1. Start the server using the appropriate command 2. Open your browser to
http://localhost: 3. Use the test client to interact with your MCP server
---
⚠️ Requirements
- Node.js v20 or later
---
Star History
🤝 Contributing
Contributions are welcome!
1. Fork the repo 2. Create a feature branch:
git checkout -b feature/amazing-feature 3. Run npm run format.write to format your code 4. Commit your changes: git commit -m "Add amazing feature"` 5. Push and open a PR
