Generates MCP server code from OpenAPI specifications
npm install openapi-mcp-generator


Generate Model Context Protocol (MCP) 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.
---
- π§ 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).
---
``bash`
npm install -g openapi-mcp-generator
> You can also use yarn global add openapi-mcp-generator or pnpm add -g openapi-mcp-generator
---
`bashGenerate an MCP server (stdio)
openapi-mcp-generator --input path/to/openapi.json --output path/to/output/dir
$3
| 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 |
| --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');
// With options
const filteredTools = await getToolsFromOpenApi('https://example.com/api-spec.json', {
baseUrl: 'https://api.example.com',
dereference: true,
excludeOperationIds: ['deletePet'],
filterFn: (tool) => tool.method.toLowerCase() === 'get',
});
`For full documentation of the programmatic API, see PROGRAMMATIC_API.md.
---
π§± 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
$3
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 |
API_KEY_ |
| Bearer | BEARER_TOKEN_ |
| Basic Auth | BASIC_USERNAME_, BASIC_PASSWORD_ |
| OAuth2 | OAUTH_CLIENT_ID_, OAUTH_CLIENT_SECRET_, OAUTH_SCOPES_ |---
π Filtering Endpoints with OpenAPI Extensions
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 defaultExamples:
`yaml
Optional root-level default
x-mcp: truepaths:
/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 installRun in stdio mode
npm startRun in web server mode
npm run start:webRun 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"`π Repository: github.com/harsha-iiiv/openapi-mcp-generator
---
MIT License β see LICENSE for full details.