{
  "markdown": "# mcp-openapi\n\n> Turn any OpenAPI/Swagger spec into MCP tools — so Claude and other AI assistants can call your REST APIs.\n\n[![npm version](https://img.shields.io/npm/v/mcp-openapi.svg)](https://www.npmjs.com/package/mcp-openapi)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![npm downloads](https://img.shields.io/npm/dm/mcp-openapi.svg)](https://www.npmjs.com/package/mcp-openapi)\n\nPoint `mcp-openapi` at any OpenAPI 3.x or Swagger 2.0 spec URL and it generates [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) tools automatically. No code generation, no config files, no boilerplate. Your AI assistant gets callable tools for every API endpoint in seconds.\n\n---\n\n## Quick Start\n\n**1. Run it** (no install required):\n\n```bash\nnpx mcp-openapi --spec https://petstore3.swagger.io/api/v3/openapi.json\n```\n\n**2. Add it to Claude Desktop** (`claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"petstore\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"mcp-openapi\",\n        \"--spec\", \"https://petstore3.swagger.io/api/v3/openapi.json\"\n      ]\n    }\n  }\n}\n```\n\n**3. Ask Claude to use it:**\n\n> \"List all available pets in the store\"\n\nClaude sees MCP tools like `find_pets_by_status`, `get_pet_by_id`, `add_pet` and calls them directly.\n\n---\n\n## Why mcp-openapi?\n\nMost MCP-to-API bridges require you to write tool definitions by hand or generate code from a spec. `mcp-openapi` skips all of that.\n\n| Feature | mcp-openapi | Hand-written MCP servers | Generic HTTP tools |\n|---------|:-----------:|:------------------------:|:------------------:|\n| Zero config setup | Yes | No | Partial |\n| OpenAPI 3.x + Swagger 2.0 | Yes | N/A | N/A |\n| Flat parameter schemas (LLM-optimized) | Yes | Manual | No |\n| Smart tool naming from operationId | Yes | Manual | No |\n| Auth (API key, Bearer, OAuth2) | Built-in | DIY | DIY |\n| Retry with exponential backoff | Built-in | DIY | DIY |\n| Response truncation for LLM context | Built-in | DIY | No |\n\n**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.\n\n---\n\n## How It Works\n\n```\nOpenAPI/Swagger Spec          mcp-openapi               AI Assistant\n     (URL or file)                                      (Claude, etc.)\n          |                         |                         |\n          |   1. Parse & validate   |                         |\n          |------------------------>|                         |\n          |                         |                         |\n          |   2. Generate MCP tools |                         |\n          |   (one per endpoint)    |                         |\n          |------------------------>|                         |\n          |                         |                         |\n          |                         |   3. Register tools     |\n          |                         |   via stdio transport   |\n          |                         |------------------------>|\n          |                         |                         |\n          |                         |   4. AI calls a tool    |\n          |                         |<------------------------|\n          |                         |                         |\n          |   5. Build & execute    |                         |\n          |   HTTP request          |                         |\n          |<------------------------|                         |\n          |                         |                         |\n          |   6. Return truncated   |                         |\n          |   response to AI        |                         |\n          |------------------------>|------------------------>|\n```\n\nEach API endpoint becomes one MCP tool:\n- **Tool name** is derived from `operationId` (converted to `snake_case`) or from `method + path`\n- **Parameters** are flattened into a single input schema (path, query, header, and body params merged)\n- **Responses** are truncated to ~50KB to stay within LLM context limits\n- **Errors** (429, 5xx) trigger automatic retries with exponential backoff (up to 3 retries)\n\n---\n\n## Claude Desktop Integration\n\nAdd any API to Claude Desktop by editing your config file:\n\n**Location:**\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n### Public API (no auth)\n\n```json\n{\n  \"mcpServers\": {\n    \"petstore\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"mcp-openapi\",\n        \"--spec\", \"https://petstore3.swagger.io/api/v3/openapi.json\"\n      ]\n    }\n  }\n}\n```\n\n### API with Bearer Token\n\n```json\n{\n  \"mcpServers\": {\n    \"github\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"mcp-openapi\",\n        \"--spec\", \"https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json\",\n        \"--auth-type\", \"bearer\",\n        \"--auth-token\", \"$GITHUB_TOKEN\",\n        \"--prefix\", \"github\",\n        \"--include\", \"listReposForAuthenticatedUser,getRepo,listIssues,createIssue\"\n      ],\n      \"env\": {\n        \"GITHUB_TOKEN\": \"ghp_your_token_here\"\n      }\n    }\n  }\n}\n```\n\n### API with API Key\n\n```json\n{\n  \"mcpServers\": {\n    \"weather\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"mcp-openapi\",\n        \"--spec\", \"https://api.weather.example.com/openapi.json\",\n        \"--auth-type\", \"api-key\",\n        \"--auth-name\", \"X-API-Key\",\n        \"--auth-value\", \"$WEATHER_API_KEY\",\n        \"--auth-in\", \"header\"\n      ],\n      \"env\": {\n        \"WEATHER_API_KEY\": \"your_key_here\"\n      }\n    }\n  }\n}\n```\n\n---\n\n## CLI Reference\n\n```bash\nnpx mcp-openapi --spec <url-or-path> [options]\n```\n\n### General Options\n\n| Option | Short | Default | Description |\n|--------|-------|---------|-------------|\n| `--spec <url\\|path>` | `-s` | *required* | OpenAPI spec URL or local file path |\n| `--config <path>` | `-c` | | JSON config file path |\n| `--base-url <url>` | | from spec | Override the API base URL |\n| `--prefix <name>` | | | Prefix for all tool names (e.g. `github` -> `github_list_repos`) |\n| `--include <patterns>` | | all | Comma-separated operationIds to include |\n| `--exclude <patterns>` | | none | Comma-separated operationIds to exclude |\n| `--timeout <ms>` | | `30000` | HTTP request timeout in milliseconds |\n| `--max-retries <n>` | | `3` | Max retries on 429/5xx responses |\n| `--header <name:value>` | `-H` | | Custom header (repeatable) |\n| `--transport <type>` | | `stdio` | Transport type: `stdio` or `sse` |\n| `--port <n>` | | `3000` | Port for SSE transport |\n| `--help` | `-h` | | Show help |\n| `--version` | `-v` | | Show version |\n| `--license-key <key>` | | | Pro license key (or `$MCP_OPENAPI_LICENSE_KEY` env) |\n| `--server <selector>` | | `0` | Select API server by index, partial URL, or exact URL |\n| `--no-doc-warnings` | | | Suppress doc quality warnings on startup |\n| `--dynamic-discovery` | | auto (100+) | Enable dynamic tool discovery for large APIs |\n\n### Auth Options\n\n**Bearer token:**\n\n| Option | Description |\n|--------|-------------|\n| `--auth-type bearer` | Use Bearer token authentication |\n| `--auth-token <token>` | The token value (supports `$ENV_VAR` syntax) |\n\n**API key:**\n\n| Option | Description |\n|--------|-------------|\n| `--auth-type api-key` | Use API key authentication |\n| `--auth-name <name>` | Header or query parameter name |\n| `--auth-value <value>` | The API key value (supports `$ENV_VAR` syntax) |\n| `--auth-in <header\\|query>` | Where to send the key (default: `header`) |\n\n**OAuth2 client credentials:**\n\n| Option | Description |\n|--------|-------------|\n| `--auth-type oauth2` | Use OAuth2 client credentials flow |\n| `--auth-client-id <id>` | OAuth2 client ID |\n| `--auth-client-secret <secret>` | OAuth2 client secret |\n| `--auth-token-url <url>` | Token endpoint URL |\n| `--auth-scopes <scopes>` | Comma-separated scopes |\n\n---\n\n## CLI Examples\n\n```bash\n# Basic usage with a remote spec\nnpx mcp-openapi --spec https://petstore3.swagger.io/api/v3/openapi.json\n\n# Local YAML spec with Bearer auth\nnpx mcp-openapi --spec ./api.yaml --auth-type bearer --auth-token '$API_KEY'\n\n# Filter to specific endpoints with a prefix\nnpx mcp-openapi --spec ./api.json --prefix myapi --include 'listUsers,getUser'\n\n# Override base URL (useful for local dev)\nnpx mcp-openapi --spec https://api.example.com/openapi.json --base-url http://localhost:3000\n\n# Add custom headers\nnpx mcp-openapi --spec ./api.json -H 'X-Custom: value' -H 'X-Another: value2'\n\n# Use a JSON config file\nnpx mcp-openapi --config ./mcp-config.json\n\n# Select staging server\nnpx mcp-openapi --spec ./api.json --server staging\n\n# Large API with dynamic discovery\nnpx mcp-openapi --spec https://api.stripe.com/openapi.json --dynamic-discovery\n```\n\n### Config File Format\n\nInstead of CLI flags, you can use a JSON config file:\n\n```json\n{\n  \"spec\": \"https://api.example.com/openapi.json\",\n  \"prefix\": \"myapi\",\n  \"include\": [\"listUsers\", \"getUser\", \"createUser\"],\n  \"auth\": {\n    \"type\": \"bearer\",\n    \"token\": \"$API_TOKEN\"\n  },\n  \"timeout\": 15000,\n  \"maxRetries\": 2,\n  \"headers\": {\n    \"X-Custom-Header\": \"value\"\n  }\n}\n```\n\nCLI arguments take precedence over config file values.\n\n---\n\n## Supported Specs\n\n| Format | Versions | File types |\n|--------|----------|------------|\n| OpenAPI | 3.0.x, 3.1.x | `.json`, `.yaml`, `.yml` |\n| Swagger | 2.0 | `.json`, `.yaml`, `.yml` |\n\nSpecs can be loaded from:\n- Remote URLs (`https://...`)\n- Local file paths (`./api.yaml`, `/absolute/path/spec.json`)\n\n---\n\n## v0.3.0 Features\n\n### Doc Quality Warnings\n\nOn startup, `mcp-openapi` checks each tool's documentation quality. If endpoints have sparse descriptions (under 50 characters), you'll see a warning:\n\n```\n[mcp-openapi] WARN: Doc quality: 11 of 47 tools have sparse documentation (<50 chars)\n[mcp-openapi] WARN:   Affected: getUser, createOrder, deleteItem, updateCart, listTags, ...\n[mcp-openapi] WARN:   LLM accuracy may be reduced for these endpoints.\n```\n\nThis helps you identify which API endpoints might cause poor LLM tool-calling accuracy. Suppress with `--no-doc-warnings`.\n\n### Server Filtering\n\nOpenAPI specs can define multiple servers (production, staging, dev). Select which one to use:\n\n```bash\n# Use first server (default behavior)\nmcp-openapi --spec api.json --server 0\n\n# Match by URL keyword\nmcp-openapi --spec api.json --server prod\n\n# Exact URL\nmcp-openapi --spec api.json --server https://api.example.com/v2\n```\n\nIf the selector doesn't match, you'll see all available servers listed.\n\n### Dynamic Tool Discovery\n\nFor 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:\n\n| Meta-tool | Description |\n|-----------|-------------|\n| `search_operations(query)` | Search tools by keyword in names, descriptions, and tags |\n| `list_by_tag(tag?)` | Browse tools by OpenAPI tag, or list all tags |\n| `get_tool_details(tool_name)` | Get full parameter schema for a specific tool |\n\nThe LLM explores the API through these meta-tools, then calls specific endpoints by name.\n\n```bash\n# Explicit opt-in\nmcp-openapi --spec large-api.json --dynamic-discovery\n\n# Auto-enabled when spec has 100+ endpoints\nmcp-openapi --spec https://api.github.com/openapi.json\n```\n\nOr via config file:\n\n```json\n{\n  \"spec\": \"https://api.stripe.com/openapi.json\",\n  \"dynamicDiscovery\": true,\n  \"auth\": { \"type\": \"bearer\", \"token\": \"$STRIPE_KEY\" }\n}\n```\n\n---\n\n## Pro Features (v0.2.0+)\n\n`mcp-openapi` includes optional Pro features for teams and power users, gated by a license key.\n\n### Custom Response Transforms\n\nShape API responses with [JMESPath](https://jmespath.org/) expressions before they reach the LLM — reducing token usage and improving accuracy:\n\n```json\n{\n  \"spec\": \"https://api.github.com/openapi.json\",\n  \"licenseKey\": \"$MCP_OPENAPI_LICENSE_KEY\",\n  \"transforms\": {\n    \"list_repos\": \"data[].{name: name, stars: stargazers_count, url: html_url}\",\n    \"list_*\": \"data[].{id: id, name: name}\"\n  }\n}\n```\n\n### Smart Response Handling\n\nInstead of hard-truncating large responses at 50KB, Pro enables intelligent truncation:\n\n- **Array slicing**: Large arrays show first N items + metadata (`\"showing 10 of 847 items\"`)\n- **Depth pruning**: Deep nested objects are summarized beyond a configurable depth\n- **Structure preservation**: You always see the shape of the data, never a mid-JSON cut\n\n```json\n{\n  \"spec\": \"./api.json\",\n  \"licenseKey\": \"$MCP_OPENAPI_LICENSE_KEY\",\n  \"response\": {\n    \"maxLength\": 50000,\n    \"arraySliceSize\": 10,\n    \"maxDepth\": 4\n  }\n}\n```\n\n### Coming Soon\n\n- **Multi-API Composition** — Load multiple OpenAPI specs into one MCP session\n- **Usage Analytics** — Track tool calls, latency, and error rates\n\n> Interested in Pro? Star the repo and [open an issue](https://github.com/Docat0209/mcp-openapi/issues) to get early access.\n\n---\n\n## Programmatic Usage\n\nYou can also use `mcp-openapi` as a library in your own MCP server:\n\n```typescript\nimport { createServer } from 'mcp-openapi';\n\nconst { server, tools, spec } = await createServer({\n  spec: 'https://petstore3.swagger.io/api/v3/openapi.json',\n  prefix: 'petstore',\n  auth: {\n    type: 'bearer',\n    token: process.env.API_TOKEN,\n  },\n});\n\nconsole.log(`Loaded ${tools.length} tools from ${spec.info.title}`);\n```\n\n---\n\n## Requirements\n\n- Node.js 18 or later\n- An OpenAPI 3.x or Swagger 2.0 spec (URL or local file)\n\n---\n\n## Contributing\n\nContributions are welcome. Here is how to get started:\n\n```bash\ngit clone https://github.com/Docat0209/mcp-openapi.git\ncd mcp-openapi\npnpm install\npnpm test\npnpm build\n```\n\nBefore submitting a PR:\n1. Add tests for new features\n2. Run `pnpm lint` and fix any issues\n3. Follow [Conventional Commits](https://www.conventionalcommits.org/) for commit messages\n\n---\n\n## Related\n\n- [graphql-to-mcp](https://www.npmjs.com/package/graphql-to-mcp) — Same zero-config approach for GraphQL APIs\n\n## License\n\nMIT\n\n---\n\n## Keywords\n\nmcp, model-context-protocol, openapi, swagger, claude, ai, llm, api, tools, rest-api, ai-tools, mcp-server\n",
  "bytes": 14200,
  "sha": "7532fa0a9b28354d2c7e58b97c96a70c5bb8ba16da4665ef4fab2d52f64fe447",
  "repo_slug": "docat0209/mcp-openapi",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_docat0209_openapi_a8495497/readme"
}