OpenAPI to MCP Generator (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.

---

✨ 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

npm install -g openapi-mcp-generator

You can also use yarn global add openapi-mcp-generator or pnpm add -g openapi-mcp-generator

---

🛠 Usage

# 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

# Generate a deployable Cloudflare Worker MCP server
openapi-mcp-generator --input path/to/openapi.json --output path/to/output/dir --transport=cloudflare-worker

CLI Options

Configuring the API base URL at runtime: the generated server reads API_BASE_URL from the environment (.env), overriding the value baked in from the OpenAPI servers list. The port resolves from --port, then the PORT env var, then 3000.

📦 Programmatic API

You can also use this package programmatically in your Node.js applications:

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:

<output_directory>/
├── .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

Cloudflare Worker

Generates a complete, deployable Cloudflare Workers project that serves the MCP server over Streamable HTTP at /mcp using the MCP SDK's WebStandardStreamableHTTPServerTransport directly (no extra framework dependency). Deploy it to your own Cloudflare account with one command:

openapi-mcp-generator --input ./openapi.json --output ./my-mcp-worker --transport cloudflare-worker
cd my-mcp-worker
npm install
npx wrangler secret put API_KEY   # set upstream API secrets (see .dev.vars.example)
npx wrangler deploy               # Wrangler logs into YOUR Cloudflare account and deploys

Highlights:

• Stateless, runs on the free Workers tier (no Durable Objects or KV). A fresh MCP server + transport is created per request (required by MCP SDK ≥ 1.26).
• Lean dependencies: just @modelcontextprotocol/sdk and zod — no extra agent framework.
• Non-secret config (e.g. API_BASE_URL) lives in wrangler.jsonc under vars; secrets are set with wrangler secret put and read from the env binding — never committed.
• Workers-native runtime: global fetch (no Node https), and argument validation uses build-time-emitted zod (no runtime eval).
• Auth is scheme-aware: API key (header/query/cookie), HTTP basic/bearer, and OAuth2 client-credentials are derived from env secrets.
• --header-passthrough, --custom-auth, --port, --insecure, --generate-lib, and --oauth-creds-in-body do not apply to this target and are ignored with a warning.

Local development: cp .dev.vars.example .dev.vars, fill in secrets, then npm run dev (serves http://localhost:8787/mcp). Connect with the MCP Inspector or, from Claude Desktop, via mcp-remote.

Transport Comparison

---

🔐 Environment Variables for Authentication

Configure auth credentials in your environment:

---

🔎 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 default

Examples:

# 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

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:<port>
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

📌 Repository: github.com/harsha-iiiv/openapi-mcp-generator

---

📄 License

MIT License — see LICENSE for full details.