{
  "markdown": "# mcp-openapi\n\n[![npm version](https://img.shields.io/npm/v/mcp-openapi-runner.svg)](https://www.npmjs.com/package/mcp-openapi-runner)\n[![CI](https://github.com/saurav61091/mcp-openapi/actions/workflows/ci.yml/badge.svg)](https://github.com/saurav61091/mcp-openapi/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)\n[![MCP](https://img.shields.io/badge/MCP-compatible-purple.svg)](https://modelcontextprotocol.io)\n\n> Turn any OpenAPI spec into MCP tools for Claude — zero config, instant API access.\n\nPoint `mcp-openapi-runner` at any OpenAPI 3.x spec and Claude can call every endpoint through natural language. No custom integration code. No manual tool definitions. **One line of config.**\n\n## Why mcp-openapi?\n\n| Without mcp-openapi | With mcp-openapi |\n|---|---|\n| Write custom MCP server per API | One config line per API |\n| Define tool schemas manually | Auto-generated from OpenAPI spec |\n| Handle auth, params, body yourself | Built-in auth + parameter handling |\n| Maintain code as API evolves | Spec changes = tools update automatically |\n\n## Quick start\n\nAdd to your **Claude Desktop** / **Claude Code** / **Cursor** / **Cline** MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"petstore\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-openapi-runner\", \"--spec\", \"https://petstore3.swagger.io/api/v3/openapi.json\"]\n    }\n  }\n}\n```\n\nThat's it. Claude can now discover and call every endpoint in that API.\n\n## Example conversation\n\n> **You:** What pets are available? Add a new dog named Buddy.\n>\n> **Claude:** Let me check what's available.\n> *[calls `list_endpoints` → discovers `findPetsByStatus`, `addPet`, ...]*\n> *[calls `call_endpoint` → `findPetsByStatus` with `status=available`]*\n>\n> There are 3 pets currently available. Now I'll add Buddy...\n> *[calls `call_endpoint` → `addPet` with `{\"name\":\"Buddy\",\"status\":\"available\"}`]*\n>\n> Done! Buddy has been added with ID 12345.\n\n## Features\n\n- **Zero config** — just point at a spec URL or file\n- **Any OpenAPI 3.x spec** — JSON or YAML, local or remote, `$ref` auto-resolved\n- **Auto-generated operationIds** — works even when the spec doesn't define them\n- **Built-in auth** — Bearer, API key, Basic auth via environment variables\n- **Endpoint filtering** — only expose the endpoints you need with `--filter`\n- **Custom headers** — pass arbitrary headers with `--header`\n- **Server URL override** — point at staging/local with `--server-url`\n- **Two-tool design** — simple `list_endpoints` → `call_endpoint` workflow\n- **Works everywhere** — Claude Desktop, Claude Code, Cursor, Cline, any MCP client\n\n## Ready-to-use configs\n\n### Stripe\n\n```json\n{\n  \"mcpServers\": {\n    \"stripe\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-openapi-runner\", \"--spec\", \"https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json\"],\n      \"env\": {\n        \"OPENAPI_BEARER_TOKEN\": \"sk_test_...\"\n      }\n    }\n  }\n}\n```\n\n### GitHub REST API\n\n```json\n{\n  \"mcpServers\": {\n    \"github\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-openapi-runner\",\n        \"--spec\", \"https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json\",\n        \"--filter\", \"repos\"],\n      \"env\": {\n        \"OPENAPI_BEARER_TOKEN\": \"ghp_...\"\n      }\n    }\n  }\n}\n```\n\n### Your internal API\n\n```json\n{\n  \"mcpServers\": {\n    \"internal\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-openapi-runner\", \"--spec\", \"http://localhost:8080/openapi.json\"],\n      \"env\": {\n        \"OPENAPI_API_KEY\": \"dev-key-123\"\n      }\n    }\n  }\n}\n```\n\n### Jira (Atlassian)\n\n```json\n{\n  \"mcpServers\": {\n    \"jira\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-openapi-runner\",\n        \"--spec\", \"https://dac-static.atlassian.com/cloud/jira/platform/swagger-v3.v3.json\",\n        \"--server-url\", \"https://your-domain.atlassian.net\",\n        \"--filter\", \"issue\"],\n      \"env\": {\n        \"OPENAPI_BASIC_USER\": \"you@company.com\",\n        \"OPENAPI_BASIC_PASS\": \"your-api-token\"\n      }\n    }\n  }\n}\n```\n\n## Authentication\n\nPass credentials via environment variables:\n\n```json\n{\n  \"mcpServers\": {\n    \"my-api\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-openapi-runner\", \"--spec\", \"https://api.example.com/openapi.json\"],\n      \"env\": {\n        \"OPENAPI_BEARER_TOKEN\": \"your-token-here\"\n      }\n    }\n  }\n}\n```\n\n| Variable | Description |\n|---|---|\n| `OPENAPI_BEARER_TOKEN` | Bearer token → `Authorization: Bearer <token>` |\n| `OPENAPI_API_KEY` | API key value |\n| `OPENAPI_API_KEY_HEADER` | Header name for API key (default: `X-Api-Key`) |\n| `OPENAPI_BASIC_USER` | HTTP Basic auth username |\n| `OPENAPI_BASIC_PASS` | HTTP Basic auth password |\n\n## CLI options\n\n```\nnpx mcp-openapi-runner --spec <url-or-path> [options]\n\nOptions:\n  --spec         Path or URL to an OpenAPI 3.x spec (JSON or YAML)\n  --server-url   Override the base URL from the spec\n  --filter       Only expose endpoints matching a pattern (path, tag, or operationId)\n  --header       Add custom header to all requests (\"Name: Value\", repeatable)\n  --help         Show help\n```\n\n### Examples\n\n```bash\n# Basic usage\nnpx mcp-openapi-runner --spec https://petstore3.swagger.io/api/v3/openapi.json\n\n# Only pet-related endpoints\nnpx mcp-openapi-runner --spec ./openapi.yaml --filter pets\n\n# Point at local dev server\nnpx mcp-openapi-runner --spec ./openapi.yaml --server-url http://localhost:3000\n\n# Custom headers\nnpx mcp-openapi-runner --spec ./openapi.yaml --header \"X-Tenant: acme\" --header \"X-Debug: true\"\n\n# With auth\nOPENAPI_BEARER_TOKEN=mytoken npx mcp-openapi-runner --spec https://api.example.com/openapi.json\n```\n\n## Tools\n\n`mcp-openapi-runner` exposes exactly two tools:\n\n| Tool | Description |\n|---|---|\n| `list_endpoints` | Returns all operations grouped by tag with operationIds, methods, paths, and parameters |\n| `call_endpoint` | Executes any operation by `operationId` with path/query/header/body parameters |\n\nThe two-tool design means Claude always has a clear workflow: **discover → call**.\n\n## How it works\n\n1. Loads the OpenAPI spec from the given URL or file path\n2. Dereferences all `$ref` schemas using `@apidevtools/swagger-parser`\n3. Applies endpoint filter if `--filter` is set\n4. Registers two MCP tools with the connected client\n5. `list_endpoints` generates a human+LLM-readable summary of all operations\n6. `call_endpoint` resolves params, builds the URL, attaches auth + custom headers, returns the response\n\n## Requirements\n\n- Node.js 18+\n- OpenAPI 3.x spec (JSON or YAML, local file or URL)\n\n## Contributing\n\nContributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## License\n\nMIT\n",
  "bytes": 6775,
  "sha": "312040ccbbd7ebf5f23718b5b906609adb84a752db0843b99bb6f4594f338096",
  "repo_slug": "saurav61091/mcp-openapi",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_saurav61091_mcp_openapi_runner_f86d6dee/readme"
}