openapi-to-mcp

Turn any OpenAPI spec into a ready-to-run MCP server in seconds.

mcp-gen generate --input openapi.json --out ./my-server

No boilerplate. No manual wiring. Just a working Model Context Protocol server with every endpoint mapped to a tool, example responses included.

---

Why

MCP became the standard way to expose APIs to AI agents in 2025/26. Writing MCP servers by hand means repeating the same scaffolding for every project — parsing specs, registering tools, handling schemas. openapi-to-mcp eliminates that entirely.

You bring the spec. The CLI brings the server.

---

How it works

sequenceDiagram
    participant User
    participant CLI
    participant Parser
    participant Generator
    participant Output

    User->>CLI: mcp-gen generate --input api.yaml
    CLI->>Parser: validate & parse OpenAPI v3
    Parser->>Generator: internal AST (tools, models, examples)
    Generator->>Output: render Handlebars templates
    Output-->>User: TypeScript MCP server project

Loading

Each path + method in your spec becomes an MCP tool with:

• Typed input schema derived from parameters and request body
• Example response from the spec (or a NotImplemented stub)
• Full JSDoc comments

---

Requirements

• Node.js 20+
• npm 9+

---

Installation

# Clone and install
git clone https://github.com/your-username/openapi-to-mcp.git
cd openapi-to-mcp
npm install
npm run build

npm publish coming soon — npm install -g mcp-gen will work once released.

---

Usage

Validate a spec

node dist/cli/index.js validate --input ./api/openapi.json

✔ Spec is valid

  Tools: 12  Models: 6  Base URL: https://api.example.com

Generate a server

node dist/cli/index.js generate \
  --input ./api/openapi.json \
  --out ./generated/my-server

✔ Generation complete

  ✓ 7 files created

    /generated/my-server/src/server.ts
    /generated/my-server/src/models.ts
    /generated/my-server/package.json
    /generated/my-server/tsconfig.json
    /generated/my-server/README.md
    /generated/my-server/Dockerfile
    /generated/my-server/.github/workflows/ci.yml

Run the generated server

cd generated/my-server
npm install
npm run build
npm start

Accepts URLs too

node dist/cli/index.js generate \
  --input https://petstore3.swagger.io/api/v3/openapi.json \
  --out ./petstore-mcp

---

CLI Reference

Flag	Description	Default
--input, -i	Path or URL to the OpenAPI spec (JSON or YAML)	required
--out, -o	Output directory for the generated project	./mcp-server
--lang, -l	Target language: typescript	typescript
--force, -f	Overwrite existing files without prompting	false
--name	Override the server name	derived from spec title
--version	Override the server version	derived from spec

---

Generated project structure

my-server/
├── src/
│   ├── server.ts        # MCP server — tool definitions + handlers
│   └── models.ts        # TypeScript interfaces from OpenAPI schemas
├── .github/
│   └── workflows/
│       └── ci.yml       # GitHub Actions: build + test
├── Dockerfile           # Multi-stage production image
├── package.json
├── tsconfig.json
└── README.md            # Usage guide for the generated server

---

Connect to Claude Desktop

Add the generated server to your claude_desktop_config.json:

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/absolute/path/to/my-server/dist/server.js"]
    }
  }
}

Restart Claude Desktop. Your API tools will appear automatically.

---

Implement handlers

The generated src/server.ts returns spec examples by default. Replace stubs with real logic:

case "get_users_id": {
  const user = await db.users.findById(args.id);
  return {
    content: [{ type: "text", text: JSON.stringify(user) }],
  };
}

Tools without an example response in the spec will throw NotImplemented — the CLI warns you which ones upfront.

---

Development

# Run tests
npm test

# Type-check only
npx tsc --noEmit

# Try the example spec
node dist/cli/index.js generate --input examples/petstore.json --out /tmp/petstore --force

---

Roadmap

Week	Status	Scope
0–1	✅ Done	CLI, OpenAPI v3 parser, TypeScript generator, 7-file scaffold
2	🔜 Next	Python/FastAPI target, YAML input support
3	Planned	Dockerfile polish, integration tests, CI template improvements
4	Planned	Interactive CLI mode, npm/pip publish
5	Planned	Incremental generation — preserve custom code blocks
6	Planned	Release candidate, Product Hunt launch

---

Known limitations

• OpenAPI v2 (Swagger) is not supported — v3.x only
• oneOf / anyOf / discriminator schemas are partially handled (MVP)
• Python target is not yet implemented
• copy-templates script uses cp — on Windows, change to xcopy in package.json

---

License

MIT © 2026