openapi-to-mcp

Generate a lean MCP server from any OpenAPI spec. One command — give it a spec URL or file, get a complete TypeScript MCP server with tools for every API endpoint.

Quick Start

npx @softwaresavants/openapi-to-mcp https://petstore3.swagger.io/api/v3/openapi.json

That's it. You now have a working MCP server in ./swagger-petstore-openapi-3-0-mcp/.

cd swagger-petstore-openapi-3-0-mcp
npm install
cp .env.example .env   # fill in your API key
npm run build
npm start

Usage

# From a URL
openapi-to-mcp https://api.example.com/openapi.json

# From a local file (JSON or YAML)
openapi-to-mcp ./api-spec.yaml

# Custom output directory and name
openapi-to-mcp spec.json -o ./my-mcp-server --name my-product

# Only include specific endpoints
openapi-to-mcp spec.json --include "/pets/**" "/users/**"

# Exclude endpoints
openapi-to-mcp spec.json --exclude "/admin/**" "/internal/**"

# Overwrite existing output
openapi-to-mcp spec.json -o ./existing-dir --force

Programmatic API

Use as a library in your own tools:

import { generateMcpServer } from "@softwaresavants/openapi-to-mcp";

// Parse only (no file output)
const { spec } = await generateMcpServer("https://api.example.com/openapi.json");
console.log(`Found ${spec.tools.length} tools`);

// Parse + generate
const { files } = await generateMcpServer("https://api.example.com/openapi.json", {
  outputDir: "./my-mcp-server",
  name: "my-product",
  include: ["/pets/**"],
});

What It Generates

A complete MCP server project based on the mcp-starter template:

my-product-mcp/
├── package.json
├── tsconfig.json
├── .env.example          # Pre-filled with your API's base URL
├── .gitignore
├── README.md
└── src/
    ├── index.ts           # Server entry — all tools registered
    ├── auth.ts            # API key + OAuth token auth
    ├── types.ts           # ApiConfig type
    ├── oauth-provider.ts  # Proxy OAuth provider
    ├── transports/
    │   ├── stdio.ts       # Stdio transport (default)
    │   ├── http.ts        # HTTP + OAuth transport
    │   └── sse.ts         # SSE transport (dev/testing)
    └── tools/
        ├── list_pets.ts   # One file per API operation
        ├── get_pet.ts
        └── ...

Three Transport Modes

Generated servers support all three transport modes out of the box:

npm start          # Stdio — API key auth (default, for Claude Desktop)
npm run start:http # HTTP — OAuth 2.1 (production, multi-user)
npm run start:sse  # SSE — API key auth (dev/testing, browser clients)

Design Philosophy

This tool generates MCP servers that are lean by design:

• Token-efficient descriptions. Tool descriptions are capped at 80 characters. Every character in a tool description costs tokens on every LLM request — bloated descriptions waste money and context window.
• One tool per operation. Each API endpoint becomes exactly one MCP tool with a clean Zod schema. No god-tools, no mega-handlers.
• Working OAuth out of the box. The generated HTTP transport uses ProxyOAuthServerProvider from the MCP SDK — real OAuth 2.1 with PKCE, not placeholder code.
• Claude Desktop compatible. Tool names are auto-truncated to 64 characters with collision detection. Generated servers work with Claude Desktop without manual fixes.
• Full $ref dereferencing. Uses @apidevtools/swagger-parser to resolve all $ref references, including deeply nested and cross-file references. No "missing schema" surprises.
• Filter, don't bloat. Use --include/--exclude to generate only the tools that matter. 5-10 tools is ideal — fewer tools means the LLM picks the right one every time.

Examples

Check the examples/ directory for complete generated servers you can browse:

Example	Source Spec	Tools	Description
petstore-mcp	Swagger Petstore	19	Classic pet store — CRUD pets, orders, users
notion-mcp	Notion API	13	Blocks, databases, pages, users

Each example is a complete, type-checked project — browse src/tools/ to see what the generated tool code looks like.

Options

Flag	Description	Default
-o, --output <dir>	Output directory	./<server-name>-mcp
-n, --name <name>	Server name	From spec info.title
--include <patterns...>	Only include paths matching these globs	All paths
--exclude <patterns...>	Exclude paths matching these globs	None
--force	Overwrite existing output directory	Prompt
-h, --help	Show help

Need a Production MCP Server?

This tool generates a solid starting point. For a production-grade MCP server with custom auth, permissions, and ongoing maintenance — talk to us.

Software Savants — the AI-native product studio. We build lean MCP servers that don't bloat the context window.

License

MIT