mcp-openapi

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

Pointmcp-openapiat any OpenAPI 3.x or Swagger 2.0 spec URL and it generatesModel 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.

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

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

"List all available pets in the store"

Claude sees MCP tools likefind_pets_by_status,get_pet_by_id,add_petand calls them directly.

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

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

OpenAPI/Swagger Spec mcp-openapi AI Assistant (URL or file) (Claude, etc.) | | | | 1. Parse & validate | | |------------------------>| | | | | | 2. Generate MCP tools | | | (one per endpoint) | | |------------------------>| | | | | | | 3. Register tools | | | via stdio transport | | |------------------------>| | | | | | 4. AI calls a tool | | |<------------------------| | | | | 5. Build & execute | | | HTTP request | | |<------------------------| | | | | | 6. Return truncated | | | response to AI | | |------------------------>|------------------------>|

- Tool nameis derived fromoperationId(converted tosnake_case) or frommethod + path
- Parametersare flattened into a single input schema (path, query, header, and body params merged)
- Responsesare truncated to ~50KB to stay within LLM context limits
- Errors(429, 5xx) trigger automatic retries with exponential backoff (up to 3 retries)

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

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

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

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

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

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

# 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

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.

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

On startup,mcp-openapichecks 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.

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.

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

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

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

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

{ "spec": "https://api.github.com/openapi.json", "licenseKey": "$MCP_OPENAPI_LICENSE_KEY", "transforms": { "list_repos": "data[].{name: name, stars: stargazers_count, url: html_url}", "list_*": "data[].{id: id, name: name}" } }

Instead of hard-truncating large responses at 50KB, Pro enables intelligent truncation:

- Array slicing: Large arrays show first N items + metadata ("showing 10 of 847 items")
- Depth pruning: Deep nested objects are summarized beyond a configurable depth
- Structure preservation: You always see the shape of the data, never a mid-JSON cut

{ "spec": "./api.json", "licenseKey": "$MCP_OPENAPI_LICENSE_KEY", "response": { "maxLength": 50000, "arraySliceSize": 10, "maxDepth": 4 } }

- Multi-API Composition— Load multiple OpenAPI specs into one MCP session
- Usage Analytics— Track tool calls, latency, and error rates

Interested in Pro? Star the repo andopen an issueto get early access.

import { createServer } from 'mcp-openapi'; const { server, tools, spec } = await createServer({ spec: 'https://petstore3.swagger.io/api/v3/openapi.json', prefix: 'petstore', auth: { type: 'bearer', token: process.env.API_TOKEN, }, }); console.log(Loaded ${tools.length} tools from ${spec.info.title});

git clone https://github.com/Docat0209/mcp-openapi.git cd mcp-openapi pnpm install pnpm test pnpm build

- Add tests for new features
- Runpnpm lintand fix any issues
- FollowConventional Commitsfor commit messages

- graphql-to-mcp— Same zero-config approach for GraphQL APIs

Converts OpenAPI specifications into MCP tools, enabling AI clients to interact with external APIs seamlessly.