openapi-mcp-bridge

Turn any OpenAPI/Swagger API into Model Context Protocol tools. Point the bridge at a spec (URL or local file) and every endpoint becomes an MCP tool that an AI assistant — Claude Desktop, or any MCP client — can call directly. The bridge constructs the real HTTP request, sends it, and returns the response to the model.

• 🔧 One tool per endpoint — names from operationId, JSON Schema inputs built from parameters and request bodies.
• 📥 OpenAPI 3.x and Swagger 2.0 — both normalised to the same model.
• 🔌 stdio transport built on the official mcp SDK.
• 🔒 No secrets in code — every credential comes from an environment variable.
• ✅ Typed, tested, and linted.

Installation

pip install openapi-mcp-bridge

Or install it as an isolated CLI tool:

pipx install openapi-mcp-bridge

It requires Python 3.10+.

Quickstart

List the tools generated from the public Swagger Petstore spec (this does not start a server — handy for inspecting what will be exposed):

openapi-mcp-bridge --spec https://petstore3.swagger.io/api/v3/openapi.json --list-tools

Run it as an MCP server over stdio:

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

You can also invoke it as a module:

python -m openapi_mcp_bridge --spec ./openapi.yaml

Use with Claude Desktop

Add an entry to your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "petstore": {
      "command": "openapi-mcp-bridge",
      "args": ["--spec", "https://petstore3.swagger.io/api/v3/openapi.json"],
      "env": {
        "OPENAPI_MCP_TOKEN": "your-bearer-token-here"
      }
    }
  }
}

If you do not have the console script on your PATH, you can run it with uv without installing anything:

{
  "mcpServers": {
    "petstore": {
      "command": "uvx",
      "args": [
        "openapi-mcp-bridge",
        "--spec",
        "https://petstore3.swagger.io/api/v3/openapi.json"
      ]
    }
  }
}

Restart Claude Desktop after editing the config. The same command/args/env shape works for any MCP client (e.g. Cursor, Continue, or a custom one).

Command-line options

Configuration & authentication

Credentials and connection settings are read from environment variables. No secret is ever stored in code or in the spec.

A bearer token takes priority over basic credentials. Need a custom auth header the spec doesn't describe? Use OPENAPI_MCP_EXTRA_HEADERS, e.g. {"X-Custom-Auth": "value"}.

How it works

1. Load the spec from a URL or file (JSON or YAML) and resolve intra-document $ref pointers, with cycle protection.
2. Normalise OpenAPI 3.x / Swagger 2.0 into a single internal model of operations, parameters, request bodies, and security schemes.
3. Generate one MCP tool per operation. Path/query/header parameters become top-level JSON Schema properties; the request body becomes a body property.
4. Proxy each tool call to a real HTTP request — substituting path parameters, attaching the query string, injecting auth, and sending the body — then return the status line and response body to the model.

Development

git clone https://github.com/sssdavid529/openapi-mcp-bridge.git
cd openapi-mcp-bridge
python -m venv .venv && pip install -e ".[dev]"
ruff check . && ruff format --check . && pytest

See CONTRIBUTING.md for more.

License

MIT