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

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. Filter (optional) by tags to expose only the endpoints your AI assistant needs.

4. Generate one MCP tool per operation. Path/query/header parameters become top-level JSON Schema properties; the request body becomes a body property.

5. 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