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

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