Openapi

mcp-openapi

Turn any OpenAPI/Swagger spec into MCP tools — so Claude and other AI assistants can call your REST APIs.

Point mcp-openapi at any OpenAPI 3.x or Swagger 2.0 spec URL and it generates Model Context Protocol (MCP) tools automatically. No code generation, no config files, no boilerplate. Your AI assistant gets callable tools for every API endpoint in seconds.

---

Quick Start

1. Run it (no install required):

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

2. Add it to Claude Desktop (claude_desktop_config.json):

{

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

3. Ask Claude to use it:

"List all available pets in the store"

Claude sees MCP tools like find_pets_by_status, get_pet_by_id, add_pet and calls them directly.

---

Why mcp-openapi?

Most MCP-to-API bridges require you to write tool definitions by hand or generate code from a spec. mcp-openapi skips all of that.

Flat parameter schemas are the key differentiator. Instead of passing nested JSON objects (which LLMs frequently get wrong), mcp-openapi flattens path, query, header, and body parameters into a single flat object. This dramatically improves tool-calling accuracy.

---

How It Works

OpenAPI/Swagger Spec          mcp-openapi               AI Assistant

(URL or file) (Claude, etc.) | | |

Each API endpoint becomes one MCP tool:

• Tool name is derived from operationId (converted to snake_case) or from method + path
• Parameters are flattened into a single input schema (path, query, header, and body params merged)
• Responses are truncated to ~50KB to stay within LLM context limits
• Errors (429, 5xx) trigger automatic retries with exponential backoff (up to 3 retries)

---

Claude Desktop Integration

Add any API to Claude Desktop by editing your config file:

Location:

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

Public API (no auth)

{

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

API with Bearer Token

{

"mcpServers": { "github": { "command": "npx", "args": [ "mcp-openapi", "--spec", "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json", "--auth-type", "bearer", "--auth-token", "$GITHUB_TOKEN", "--prefix", "github", "--include", "listReposForAuthenticatedUser,getRepo,listIssues,createIssue" ], "env": { "GITHUB_TOKEN": "ghp_your_token_here" } } } }

API with API Key

{

"mcpServers": { "weather": { "command": "npx", "args": [ "mcp-openapi", "--spec", "https://api.weather.example.com/openapi.json", "--auth-type", "api-key", "--auth-name", "X-API-Key", "--auth-value", "$WEATHER_API_KEY", "--auth-in", "header" ], "env": { "WEATHER_API_KEY": "your_key_here" } } } }

---

CLI Reference

npx mcp-openapi --spec <url-or-path> [options]

General Options

Auth Options

Bearer token:

API key:

OAuth2 client credentials:

---

CLI Examples

# Basic usage with a remote spec

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

Local YAML spec with Bearer auth

npx mcp-openapi --spec ./api.yaml --auth-type bearer --auth-token '$API_KEY'

Filter to specific endpoints with a prefix

npx mcp-openapi --spec ./api.json --prefix myapi --include 'listUsers,getUser'

Override base URL (useful for local dev)

npx mcp-openapi --spec https://api.example.com/openapi.json --base-url http://localhost:3000

Add custom headers

npx mcp-openapi --spec ./api.json -H 'X-Custom: value' -H 'X-Another: value2'

Use a JSON config file

npx mcp-openapi --config ./mcp-config.json

Select staging server

npx mcp-openapi --spec ./api.json --server staging

Large API with dynamic discovery

npx mcp-openapi --spec https://api.stripe.com/openapi.json --dynamic-discovery

Config File Format

Instead of CLI flags, you can use a JSON config file:

{

"spec": "https://api.example.com/openapi.json", "prefix": "myapi", "include": ["listUsers", "getUser", "createUser"], "auth": { "type": "bearer", "token": "$API_TOKEN" }, "timeout": 15000, "maxRetries": 2, "headers": { "X-Custom-Header": "value" } }

CLI arguments take precedence over config file values.

---

Supported Specs

Specs can be loaded from:

• Remote URLs (https://...)
• Local file paths (./api.yaml, /absolute/path/spec.json)

---

v0.3.0 Features

Doc Quality Warnings

On startup, mcp-openapi checks each tool's documentation quality. If endpoints have sparse descriptions (under 50 characters), you'll see a warning:

[mcp-openapi] WARN: Doc quality: 11 of 47 tools have sparse documentation (<50 chars)

[mcp-openapi] WARN: Affected: getUser, createOrder, deleteItem, updateCart, listTags, ... [mcp-openapi] WARN: LLM accuracy may be reduced for these endpoints.

This helps you identify which API endpoints might cause poor LLM tool-calling accuracy. Suppress with --no-doc-warnings.

Server Filtering

OpenAPI specs can define multiple servers (production, staging, dev). Select which one to use:

# Use first server (default behavior)

mcp-openapi --spec api.json --server 0

Match by URL keyword

mcp-openapi --spec api.json --server prod

Exact URL

mcp-openapi --spec api.json --server https://api.example.com/v2

If the selector doesn't match, you'll see all available servers listed.

Dynamic Tool Discovery

For large APIs with 100+ endpoints, registering all tools at once can overwhelm the LLM's context. Dynamic discovery solves this by registering 3 meta-tools instead:

The LLM explores the API through these meta-tools, then calls specific endpoints by name.

# Explicit opt-in

mcp-openapi --spec large-api.json --dynamic-discovery

Auto-enabled when spec has 100+ endpoints

mcp-openapi --spec https://api.github.com/openapi.json

Or via config file:

{

"spec": "https://api.stripe.com/openapi.json", "dynamicDiscovery": true, "auth": { "type": "bearer", "token": "$STRIPE_KEY" } }

---

Pro Features (v0.2.0+)

mcp-openapi includes optional Pro features for teams and power users, gated by a license key.

Custom Response Transforms

Shape API responses with JMESPath expressions before they reach the LLM — reducing token usage and improving accuracy:

{

"spec": "https://api.github.com/openapi.json", "licenseKey": "$MCP_OPENAPI_LICENSE