Server data from the Official MCP Registry
Turn any OpenAPI/Swagger spec into MCP tools. Zero config, zero code.
Turn any OpenAPI/Swagger spec into MCP tools. Zero config, zero code.
Valid MCP server (2 strong, 4 medium validity signals). 5 known CVEs in dependencies (1 critical, 3 high severity) Package registry verified. Imported from the Official MCP Registry.
8 files analyzed · 6 issues found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
This plugin requests these system permissions. Most are normal for its category.
Add this to your MCP configuration file:
{
"mcpServers": {
"io-github-docat0209-openapi": {
"args": [
"-y",
"mcp-openapi"
],
"command": "npx"
}
}
}From the project's GitHub README.
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.
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.
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.
| Feature | mcp-openapi | Hand-written MCP servers | Generic HTTP tools |
|---|---|---|---|
| Zero config setup | Yes | No | Partial |
| OpenAPI 3.x + Swagger 2.0 | Yes | N/A | N/A |
| Flat parameter schemas (LLM-optimized) | Yes | Manual | No |
| Smart tool naming from operationId | Yes | Manual | No |
| Auth (API key, Bearer, OAuth2) | Built-in | DIY | DIY |
| Retry with exponential backoff | Built-in | DIY | DIY |
| Response truncation for LLM context | Built-in | DIY | No |
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.
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 | |
|------------------------>|------------------------>|
Each API endpoint becomes one MCP tool:
operationId (converted to snake_case) or from method + pathAdd any API to Claude Desktop by editing your config file:
Location:
~/Library/Application Support/Claude/claude_desktop_config.json%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]
| Option | Short | Default | Description |
|---|---|---|---|
--spec <url|path> | -s | required | OpenAPI spec URL or local file path |
--config <path> | -c | JSON config file path | |
--base-url <url> | from spec | Override the API base URL | |
--prefix <name> | Prefix for all tool names (e.g. github -> github_list_repos) | ||
--include <patterns> | all | Comma-separated operationIds to include | |
--exclude <patterns> | none | Comma-separated operationIds to exclude | |
--timeout <ms> | 30000 | HTTP request timeout in milliseconds | |
--max-retries <n> | 3 | Max retries on 429/5xx responses | |
--header <name:value> | -H | Custom header (repeatable) | |
--transport <type> | stdio | Transport type: stdio or sse | |
--port <n> | 3000 | Port for SSE transport | |
--help | -h | Show help | |
--version | -v | Show version | |
--license-key <key> | Pro license key (or $MCP_OPENAPI_LICENSE_KEY env) | ||
--server <selector> | 0 | Select API server by index, partial URL, or exact URL | |
--no-doc-warnings | Suppress doc quality warnings on startup | ||
--dynamic-discovery | auto (100+) | Enable dynamic tool discovery for large APIs |
Bearer token:
| Option | Description |
|---|---|
--auth-type bearer | Use Bearer token authentication |
--auth-token <token> | The token value (supports $ENV_VAR syntax) |
API key:
| Option | Description |
|---|---|
--auth-type api-key | Use API key authentication |
--auth-name <name> | Header or query parameter name |
--auth-value <value> | The API key value (supports $ENV_VAR syntax) |
--auth-in <header|query> | Where to send the key (default: header) |
OAuth2 client credentials:
| Option | Description |
|---|---|
--auth-type oauth2 | Use OAuth2 client credentials flow |
--auth-client-id <id> | OAuth2 client ID |
--auth-client-secret <secret> | OAuth2 client secret |
--auth-token-url <url> | Token endpoint URL |
--auth-scopes <scopes> | Comma-separated scopes |
# 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.
| Format | Versions | File types |
|---|---|---|
| OpenAPI | 3.0.x, 3.1.x | .json, .yaml, .yml |
| Swagger | 2.0 | .json, .yaml, .yml |
Specs can be loaded from:
https://...)./api.yaml, /absolute/path/spec.json)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.
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:
| Meta-tool | Description |
|---|---|
search_operations(query) | Search tools by keyword in names, descriptions, and tags |
list_by_tag(tag?) | Browse tools by OpenAPI tag, or list all tags |
get_tool_details(tool_name) | Get full parameter schema for a specific tool |
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" }
}
mcp-openapi includes optional Pro features for teams and power users, gated by a license key.
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_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:
"showing 10 of 847 items"){
"spec": "./api.json",
"licenseKey": "$MCP_OPENAPI_LICENSE_KEY",
"response": {
"maxLength": 50000,
"arraySliceSize": 10,
"maxDepth": 4
}
}
Interested in Pro? Star the repo and open an issue to get early access.
You can also use mcp-openapi as a library in your own MCP server:
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}`);
Contributions are welcome. Here is how to get started:
git clone https://github.com/Docat0209/mcp-openapi.git
cd mcp-openapi
pnpm install
pnpm test
pnpm build
Before submitting a PR:
pnpm lint and fix any issuesMIT
mcp, model-context-protocol, openapi, swagger, claude, ai, llm, api, tools, rest-api, ai-tools, mcp-server
Be the first to review this server!
by Modelcontextprotocol · Developer Tools
Read, search, and manipulate Git repositories programmatically
by Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.
by mcp-marketplace · Developer Tools
Create, build, and publish Python MCP servers to PyPI — conversationally.
by Microsoft · Content & Media
Convert files (PDF, Word, Excel, images, audio) to Markdown for LLM consumption
by mcp-marketplace · Developer Tools
Scaffold, build, and publish TypeScript MCP servers to npm — conversationally
by mcp-marketplace · Finance
Free stock data and market news for any MCP-compatible AI assistant.