@minamorl/openapi-mcp-bridge

@minamorl/openapi-mcp-bridge

Runtime MCP server that dynamically bridges any OpenAPI 3.x spec to MCP tools.

No code generation. No build step. One command.

Quick Start

npx @minamorl/openapi-mcp-bridge --spec https://petstore3.swagger.io/api/v3/openapi.json

Why not codegen?

Existing tools (openapi-mcp-generator, etc.) generate static TypeScript files from your OpenAPI spec. Every time the API changes, you regenerate, rebuild, redeploy.

openapi-mcp-bridge takes a different approach: runtime bridging. It reads the OpenAPI spec at startup and dynamically creates MCP tools. Update the spec → restart the server. That's it.

| | Codegen tools | openapi-mcp-bridge | |---|---|---| | API spec changes | Regenerate → rebuild → restart | Restart only | | Setup | npm install → generate → configure → build → start | npx + 1 flag | | OAuth2 | "Put token in .env" | Built-in auth flows | | Transport | stdio only | stdio + Streamable HTTP (planned) |

Usage

CLI

# From URL
openapi-mcp-bridge --spec https://api.example.com/openapi.json

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

# With auth
openapi-mcp-bridge --spec ./api.yaml --auth-type bearer --auth-token $TOKEN

# With custom base URL
openapi-mcp-bridge --spec ./api.yaml --base-url http://localhost:3000

# With custom headers
openapi-mcp-bridge --spec ./api.yaml -H "X-Custom: value"

Claude Desktop / Cursor config

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": ["@minamorl/openapi-mcp-bridge", "--spec", "https://api.example.com/openapi.json"]
    }
  }
}

Programmatic API

import { parseSpec, createBridgeServer, startStdioServer } from "@minamorl/openapi-mcp-bridge";

const doc = await parseSpec("./api.yaml");
const server = await createBridgeServer({ doc, baseUrl: "http://localhost:3000" });
await startStdioServer(server);

How It Works

OpenAPI 3.x spec (JSON/YAML/URL)
        ↓ Parse + resolve $refs
   Tool definitions (name, schema, method, path)
        ↓ Register as MCP tools
   MCP Server (stdio)
        ↓ On tool call
   HTTP request to actual API
        ↓
   Response back to LLM

1. Parser reads and validates the OpenAPI spec, resolving all $ref references
2. Mapper converts each operation to an MCP tool with proper input schemas
3. Server registers tools and handles MCP protocol
4. Executor translates tool calls into HTTP requests

Auth

# Bearer token
--auth-type bearer --auth-token YOUR_TOKEN

# API key
--auth-type api-key --auth-token YOUR_KEY --api-key-header X-API-Key

# Basic auth (token = base64 of user:pass)
--auth-type basic --auth-token BASE64_CREDENTIALS

License

MIT