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 and SSE transports — local or remote, built on the official mcp SDK.
🏷️ Tag filtering — --include-tags / --exclude-tags to expose only the endpoints your AI assistant needs.
🔒 No secrets in code — every credential comes from an environment variable.
✅ Typed, tested, and linted — 77 tests, ruff, CI across Python 3.10–3.13.

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

Filter by tags to expose only a subset of a large API:

openapi-mcp-bridge --spec https://petstore3.swagger.io/api/v3/openapi.json \
  --list-tools --include-tags pet store

Run it as an MCP server over stdio:

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

Or over SSE (HTTP + Server-Sent Events) for remote MCP clients:

openapi-mcp-bridge --spec https://petstore3.swagger.io/api/v3/openapi.json \
  --transport sse --host 0.0.0.0 --port 8080

You can also invoke it as a module:

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

Use with Claude Desktop

stdio (local)

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"
      }
    }
  }
}

SSE (remote / browser clients)

Start the bridge in SSE mode, then point your MCP client at http://localhost:8000/sse:

{
  "mcpServers": {
    "petstore": {
      "url": "http://localhost:8000/sse"
    }
  }
}

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"
      ]
    }
  }
}

Command-line options

| Option | Description | | --- | --- | | --spec (required) | OpenAPI/Swagger spec to load: an http(s) URL or a file path. | | --transport | MCP transport: stdio (default) or sse. | | --host | Host for SSE transport (default 127.0.0.1). | | --port | Port for SSE transport (default 8000). | | --base-url | Override the API server base URL declared in the spec. | | --name | MCP server name (defaults to the spec's info.title). | | --timeout | Per-request HTTP timeout in seconds (default 30). | | --include-tags | Only expose endpoints matching at least one of these tags. | | --exclude-tags | Exclude endpoints matching any of these tags. | | --list-tools | Print the generated tools and exit without starting the server. | | --version | Print the version and exit. |

Configuration & authentication

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

| Variable | Purpose | | --- | --- | | OPENAPI_MCP_BASE_URL | Override the API base URL (same as --base-url). | | OPENAPI_MCP_TOKEN | Bearer token → Authorization: Bearer <token>. | | OPENAPI_MCP_API_KEY | Secret for an apiKey scheme; the header/query name and location are taken from the spec (default header X-API-Key). | | OPENAPI_MCP_BASIC_USERNAME / OPENAPI_MCP_BASIC_PASSWORD | HTTP Basic credentials. | | OPENAPI_MCP_EXTRA_HEADERS | JSON object of extra headers merged into every request; overrides derived auth headers. | | OPENAPI_MCP_TIMEOUT | Per-request timeout in seconds (same as --timeout). | | OPENAPI_MCP_VERIFY_TLS | Set to false/0/no to disable TLS verification (not recommended). |

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

Load the spec from a URL or file (JSON or YAML) and resolve intra-document $ref pointers, with cycle protection.
Normalise OpenAPI 3.x / Swagger 2.0 into a single internal model of operations, parameters, request bodies, and security schemes.
Filter (optional) by tags to expose only the endpoints your AI assistant needs.
Generate one MCP tool per operation. Path/query/header parameters become top-level JSON Schema properties; the request body becomes a body property.
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.

Security

See SECURITY.md for details on how credentials are handled and how to report vulnerabilities.

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

MCP Servers