https://github.com/harsha-iiiv/openapi-mcp-generator
A tool that converts OpenAPI specifications to MCP server
https://github.com/harsha-iiiv/openapi-mcp-generator
Last synced: 6 months ago
JSON representation
A tool that converts OpenAPI specifications to MCP server
- Host: GitHub
- URL: https://github.com/harsha-iiiv/openapi-mcp-generator
- Owner: harsha-iiiv
- Created: 2025-03-09T08:36:06.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-04-20T07:36:55.000Z (7 months ago)
- Last Synced: 2025-04-20T08:38:13.899Z (7 months ago)
- Language: TypeScript
- Size: 92.8 KB
- Stars: 23
- Watchers: 2
- Forks: 9
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
- awesome-mcp-servers - Gentoro - Tool that generates MCP Servers based on OpenAPI specifications, simplifying the creation of custom MCP servers for different APIs. `openapi` `code-generation` `mcp` `developer-tools` `open-source` (Development Tools MCP Servers)
- awesome-mcp-servers - **openapi-mcp-generator** - A tool that converts OpenAPI specifications to MCP server `typescript` `mcp` `server` `api` `npm install harsha-iiiv/openapi-mcp-generator` (🌐 Web Development)
README
# OpenAPI to MCP Generator (openapi-mcp-generator)
[](https://www.npmjs.com/package/openapi-mcp-generator)
[](https://opensource.org/licenses/MIT)
[](https://github.com/harsha-iiiv/openapi-mcp-generator)
Generate [Model Context Protocol (MCP)](https://modelcontextprotocol.github.io/) servers from OpenAPI specifications.
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`
---
## 🛠 Usage
```bash
# Generate an MCP server (stdio)
openapi-mcp-generator --input path/to/openapi.json --output path/to/output/dir
# Generate an MCP web server with SSE
openapi-mcp-generator --input path/to/openapi.json --output path/to/output/dir --transport=web --port=3000
# Generate an MCP StreamableHTTP server
openapi-mcp-generator --input path/to/openapi.json --output path/to/output/dir --transport=streamable-http --port=3000
```
### CLI Options
| Option | Alias | Description | Default |
|--------------------|-------|-----------------------------------------------------------------------------------------------------|---------------------------------|
| `--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` |
| `--force` | | Overwrite existing files in the output directory without confirmation | `false` |
---
## 🧱 Project Structure
The generated project includes:
```
/
├── .gitignore
├── package.json
├── tsconfig.json
├── .env.example
├── src/
│ ├── index.ts
│ └── [transport-specific-files]
└── public/ # For web-based transports
└── index.html # Test client
```
Core dependencies:
- `@modelcontextprotocol/sdk` - MCP protocol implementation
- `axios` - HTTP client for API requests
- `zod` - Runtime validation
- `json-schema-to-zod` - Convert JSON Schema to Zod
- Transport-specific deps (Hono, uuid, etc.)
---
## 📡 Transport Modes
### Stdio (Default)
Communicates with MCP clients via standard input/output. Ideal for local development or integration with LLM tools.
### Web Server with SSE
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
### StreamableHTTP
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
### Transport Comparison
| 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 | `API_KEY_` |
| Bearer | `BEARER_TOKEN_` |
| Basic Auth | `BASIC_USERNAME_`, `BASIC_PASSWORD_` |
| OAuth2 | `OAUTH_CLIENT_ID_`, `OAUTH_CLIENT_SECRET_`, `OAUTH_SCOPES_` |
---
## ▶️ 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
```
### Testing Web-Based Servers
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. Commit your changes: `git commit -m "Add amazing feature"`
4. Push and open a PR
📌 Repository: [github.com/harsha-iiiv/openapi-mcp-generator](https://github.com/harsha-iiiv/openapi-mcp-generator)
---
## 📄 License
MIT License — see [LICENSE](./LICENSE) for full details.