{"_id":"@abhishekkumar00019/swagger-mcp","_rev":"3-749fcb67a16b1b1f6c722ec9b9ac47c0","name":"@abhishekkumar00019/swagger-mcp","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.0":{"name":"@abhishekkumar00019/swagger-mcp","version":"1.0.0","keywords":["mcp","swagger","openapi","model-context-protocol","ai-tools","claude","copilot","cursor"],"author":{"name":"Abhishek Kumar"},"license":"MIT","_id":"@abhishekkumar00019/swagger-mcp@1.0.0","maintainers":[{"name":"abhishekkumar00019","email":"itachi0uchiha19@gmail.com"}],"homepage":"https://github.com/itachiuchihadev/swagger-mcp#readme","bugs":{"url":"https://github.com/itachiuchihadev/swagger-mcp/issues"},"bin":{"swagger-mcp":"dist/index.js"},"dist":{"shasum":"cf9748a5e3bb09d76457d190a67a3f795b17ac4e","tarball":"https://registry.npmjs.org/@abhishekkumar00019/swagger-mcp/-/swagger-mcp-1.0.0.tgz","fileCount":27,"integrity":"sha512-JCvLNv6IOShLoqCprChpFNZZyR6rLmiSJx1YZHlFEnomSdRAteZM7HTSLh73p+LrxpH+jJF92vHamAwQqoW15A==","signatures":[{"sig":"MEUCIF0P7H5lJ+wWwl6FN9xD+btJGKHrsq0B+PPC+Vm+v6R1AiEA0utuPIbWz1KzXD3rvcO+PoJGml2GC0B4zA+URRqADmw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":78299},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","gitHead":"6fc7190c63c86d973bbdc578683d6c67881da0ec","scripts":{"dev":"tsx src/index.ts","test":"vitest run","build":"tsc","start":"node dist/index.js","test:watch":"vitest","prepublishOnly":"npm run test && npm run build"},"_npmUser":{"name":"abhishekkumar00019","email":"itachi0uchiha19@gmail.com"},"repository":{"url":"git+https://github.com/itachiuchihadev/swagger-mcp.git","type":"git"},"_npmVersion":"10.6.0","description":"Dynamic MCP server that converts Swagger/OpenAPI specs into callable MCP tools","directories":{},"_nodeVersion":"24.11.1","dependencies":{"zod":"^3.25.67","openapi-types":"^12.1.3","@modelcontextprotocol/sdk":"^1.12.1","@apidevtools/swagger-parser":"^10.1.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.20.3","vitest":"^4.1.10","typescript":"^5.8.3","@types/node":"^22.15.34"},"_npmOperationalInternal":{"tmp":"tmp/swagger-mcp_1.0.0_1784735921489_0.3268355455180767","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@abhishekkumar00019/swagger-mcp","version":"1.0.1","keywords":["mcp","swagger","openapi","model-context-protocol","ai-tools","claude","copilot","cursor"],"author":{"name":"Abhishek Kumar"},"license":"MIT","_id":"@abhishekkumar00019/swagger-mcp@1.0.1","maintainers":[{"name":"abhishekkumar00019","email":"itachi0uchiha19@gmail.com"}],"homepage":"https://github.com/itachiuchihadev/swagger-mcp#readme","bugs":{"url":"https://github.com/itachiuchihadev/swagger-mcp/issues"},"bin":{"swagger-mcp":"dist/index.js"},"dist":{"shasum":"bab2c27a6667b305b398f9de029be33ead9c2286","tarball":"https://registry.npmjs.org/@abhishekkumar00019/swagger-mcp/-/swagger-mcp-1.0.1.tgz","fileCount":27,"integrity":"sha512-vXvBAqOouSBUFMj3pA8+Dh7xooPnIxLr1sm1mK2EyaTq1YKckJOugzVQCFTCqsurTkVhWl4CvIcdwCm0s2KjeA==","signatures":[{"sig":"MEUCIQDjo/6EnpN4UDIcm6noo+n60iTWGzKfd1FpbkdL9djcewIgaM0xdzW3sb8D4Je6blMF+3ziSrofW02JPEfu6eStQ04=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":78299},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","gitHead":"439d8251e93906a59784391e4a142e7136308c76","scripts":{"dev":"tsx src/index.ts","test":"vitest run","build":"tsc","start":"node dist/index.js","test:watch":"vitest","prepublishOnly":"npm run test && npm run build"},"_npmUser":{"name":"abhishekkumar00019","email":"itachi0uchiha19@gmail.com"},"repository":{"url":"git+https://github.com/itachiuchihadev/swagger-mcp.git","type":"git"},"_npmVersion":"10.8.2","description":"Dynamic MCP server that converts Swagger/OpenAPI specs into callable MCP tools","directories":{},"_nodeVersion":"20.20.2","dependencies":{"zod":"^3.25.67","openapi-types":"^12.1.3","@modelcontextprotocol/sdk":"^1.12.1","@apidevtools/swagger-parser":"^10.1.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.20.3","vitest":"^4.1.10","typescript":"^5.8.3","@types/node":"^22.15.34"},"_npmOperationalInternal":{"tmp":"tmp/swagger-mcp_1.0.1_1784737151605_0.9462173764081523","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@abhishekkumar00019/swagger-mcp","version":"1.0.2","description":"Dynamic MCP server that converts Swagger/OpenAPI specs into callable MCP tools","type":"module","main":"dist/index.js","bin":{"swagger-mcp":"dist/index.js"},"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/itachiuchihadev/swagger-mcp.git"},"author":{"name":"Abhishek Kumar"},"license":"MIT","scripts":{"build":"tsc","prepublishOnly":"npm run test && npm run build","dev":"tsx src/index.ts","start":"node dist/index.js","test":"vitest run","test:watch":"vitest"},"keywords":["mcp","swagger","openapi","model-context-protocol","ai-tools","claude","copilot","cursor"],"dependencies":{"@apidevtools/swagger-parser":"^10.1.1","@modelcontextprotocol/sdk":"^1.12.1","openapi-types":"^12.1.3","zod":"^3.25.67"},"devDependencies":{"@types/node":"^22.15.34","tsx":"^4.20.3","typescript":"^5.8.3","vitest":"^4.1.10"},"_id":"@abhishekkumar00019/swagger-mcp@1.0.2","gitHead":"61e698df57dd6ac05084b366066f8f1ce20b4a2b","types":"./dist/index.d.ts","bugs":{"url":"https://github.com/itachiuchihadev/swagger-mcp/issues"},"homepage":"https://github.com/itachiuchihadev/swagger-mcp#readme","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-ZrgHocJSQkMPB3NJEnfwyeIDs6yAZA8Bz9X4ZNKdg1VByjUX2vLt3Tx5i71rk1DFWdU9367ESJ9DUCEacqYINg==","shasum":"534caa3b571c8430d26ba3b85c19ea019ed99f59","tarball":"https://registry.npmjs.org/@abhishekkumar00019/swagger-mcp/-/swagger-mcp-1.0.2.tgz","fileCount":27,"unpackedSize":83094,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQC5fsNf2TVLfcAJCbPmvCFn7VP7vvlOp8Maieht33azowIhAPMoIgRnP5AjPv4Bga3MuOSHxEmywiapGTFMbleQEv5z"}]},"_npmUser":{"name":"abhishekkumar00019","email":"itachi0uchiha19@gmail.com"},"directories":{},"maintainers":[{"name":"abhishekkumar00019","email":"itachi0uchiha19@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/swagger-mcp_1.0.2_1787237721911_0.5366235145120046"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-22T15:58:41.303Z","modified":"2026-08-20T14:55:22.248Z","1.0.0":"2026-07-22T15:58:41.654Z","1.0.1":"2026-07-22T16:19:11.748Z","1.0.2":"2026-08-20T14:55:22.055Z"},"bugs":{"url":"https://github.com/itachiuchihadev/swagger-mcp/issues"},"author":{"name":"Abhishek Kumar"},"license":"MIT","homepage":"https://github.com/itachiuchihadev/swagger-mcp#readme","keywords":["mcp","swagger","openapi","model-context-protocol","ai-tools","claude","copilot","cursor"],"repository":{"type":"git","url":"git+https://github.com/itachiuchihadev/swagger-mcp.git"},"description":"Dynamic MCP server that converts Swagger/OpenAPI specs into callable MCP tools","maintainers":[{"name":"abhishekkumar00019","email":"itachi0uchiha19@gmail.com"}],"readme":"# @abhishekkumar00019/swagger-mcp\n\n[![npm version](https://img.shields.io/npm/v/@abhishekkumar00019/swagger-mcp.svg)](https://www.npmjs.com/package/@abhishekkumar00019/swagger-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue.svg)](https://modelcontextprotocol.io)\n\n> A dynamic [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that converts any Swagger 2.0 or OpenAPI 3.x specification into callable MCP tools on the fly.\n\nPoint it at any OpenAPI/Swagger JSON or YAML spec URL, and every API endpoint automatically becomes an interactive tool for Claude, Copilot, ChatGPT, Cursor, Windsurf, and other MCP-enabled clients.\n\n---\n\n## ✨ Features\n\n- 🔄 **Dynamic Tool Generation** — Automatically parses Swagger 2.0 & OpenAPI 3.x specs at startup.\n- 🛠️ **Zero Boilerplate** — Give it a spec URL and every endpoint is instantly exposed as an MCP tool.\n- 🔐 **Flexible Auth Support** — Bearer Tokens, API Keys, and Basic Auth configured effortlessly via env vars or CLI flags.\n- 🌐 **Smart Base URL Resolution** — Auto-derives base URL from config → spec server definition → spec origin URL.\n- 🔁 **Hot Reloading** — Re-fetch and re-parse the spec live at runtime using the `_swagger_mcp_reload` tool.\n- 📝 **Rich Schemas & Descriptions** — Translates OpenAPI parameters and request bodies into strict JSON schemas for precise LLM tool calling.\n- ⏱️ **Configurable Timeouts & Custom Headers** — Easily set custom request headers and request timeout thresholds.\n\n---\n\n## 🚀 Quick Start\n\n### Option A: Direct via `npx` (No Installation Required)\n\n```bash\nSWAGGER_MCP_SPEC_URL=https://petstore.swagger.io/v2/swagger.json npx @abhishekkumar00019/swagger-mcp\n```\n\n### Option B: Global NPM Installation\n\n```bash\nnpm install -g @abhishekkumar00019/swagger-mcp\n\nSWAGGER_MCP_SPEC_URL=https://petstore.swagger.io/v2/swagger.json swagger-mcp\n```\n\n### Option C: Local Repository Setup\n\n1. **Clone & Install Dependencies:**\n   ```bash\n   git clone https://github.com/itachiuchihadev/swagger-mcp.git\n   cd swagger-mcp\n   npm install\n   ```\n\n2. **Build the Project:**\n   ```bash\n   npm run build\n   ```\n\n3. **Run locally:**\n   ```bash\n   SWAGGER_MCP_SPEC_URL=https://petstore.swagger.io/v2/swagger.json node dist/index.js\n   ```\n\n---\n\n## ⚙️ MCP Client Configurations\n\nBelow are sample configurations for popular MCP clients using `npx @abhishekkumar00019/swagger-mcp`.\n\n### 1. Claude Desktop\n\nAdd to your `claude_desktop_config.json`:\n- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"swagger-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@abhishekkumar00019/swagger-mcp\"],\n      \"env\": {\n        \"SWAGGER_MCP_SPEC_URL\": \"https://petstore.swagger.io/v2/swagger.json\",\n        \"SWAGGER_MCP_BEARER_TOKEN\": \"your-api-token-here\"\n      }\n    }\n  }\n}\n```\n\n---\n\n### 2. Claude Code (CLI)\n\nAdd directly via the Claude Code CLI:\n\n```bash\nclaude mcp add swagger-mcp -- npx -y @abhishekkumar00019/swagger-mcp --spec-url https://petstore.swagger.io/v2/swagger.json\n```\n\nOr add to `.mcp.json` in your project root:\n\n```json\n{\n  \"mcpServers\": {\n    \"swagger-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@abhishekkumar00019/swagger-mcp\"],\n      \"env\": {\n        \"SWAGGER_MCP_SPEC_URL\": \"https://petstore.swagger.io/v2/swagger.json\"\n      }\n    }\n  }\n}\n```\n\n---\n\n### 3. GitHub Copilot / VS Code\n\nAdd to `.vscode/mcp.json` in your workspace or global VS Code settings:\n\n```json\n{\n  \"server\": {\n    \"swagger-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@abhishekkumar00019/swagger-mcp\"],\n      \"env\": {\n        \"SWAGGER_MCP_SPEC_URL\": \"https://petstore.swagger.io/v2/swagger.json\",\n        \"SWAGGER_MCP_API_KEY\": \"your-api-key\"\n      }\n    }\n  }\n}\n```\n\n---\n\n### 4. Cursor\n\nAdd to `.cursor/mcp.json` or configure in **Cursor Settings → Features → MCP**:\n\n```json\n{\n  \"mcpServers\": {\n    \"swagger-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@abhishekkumar00019/swagger-mcp\"],\n      \"env\": {\n        \"SWAGGER_MCP_SPEC_URL\": \"https://petstore.swagger.io/v2/swagger.json\"\n      }\n    }\n  }\n}\n```\n\n---\n\n### 5. Windsurf\n\nAdd to `~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"swagger-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@abhishekkumar00019/swagger-mcp\"],\n      \"env\": {\n        \"SWAGGER_MCP_SPEC_URL\": \"https://petstore.swagger.io/v2/swagger.json\"\n      }\n    }\n  }\n}\n```\n\n---\n\n### 6. Roo Code / Cline (VS Code Extension)\n\nAdd to `cline_mcp_settings.json` (or `roo_code_mcp_settings.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"swagger-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@abhishekkumar00019/swagger-mcp\"],\n      \"env\": {\n        \"SWAGGER_MCP_SPEC_URL\": \"https://petstore.swagger.io/v2/swagger.json\"\n      }\n    }\n  }\n}\n```\n\n---\n\n### 7. ChatGPT & OpenAI (Custom GPTs / Assistants / API)\n\n**Direct OpenAPI Spec Import (Native Custom GPT Actions):**\nChatGPT Custom GPTs support OpenAPI specifications natively. You can directly import your Swagger/OpenAPI JSON/YAML spec URL in the **Actions** section of the Custom GPT Builder without needing an intermediate server.\n\n**Via MCP HTTP/SSE Gateway:**\nIf connecting ChatGPT or OpenAI agents to this MCP server via an HTTP/SSE bridge (e.g., using `supergateway` or `mcp-remote`), start `swagger-mcp` with an SSE proxy:\n\n```bash\nnpx supergateway --stdio \"npx -y @abhishekkumar00019/swagger-mcp --spec-url https://petstore.swagger.io/v2/swagger.json\" --port 8000\n```\n\n---\n\n### 8. Zed Editor\n\nAdd to `~/.config/zed/settings.json`:\n\n```json\n{\n  \"context_servers\": {\n    \"swagger-mcp\": {\n      \"command\": {\n        \"path\": \"npx\",\n        \"args\": [\"-y\", \"@abhishekkumar00019/swagger-mcp\"]\n      },\n      \"env\": {\n        \"SWAGGER_MCP_SPEC_URL\": \"https://petstore.swagger.io/v2/swagger.json\"\n      }\n    }\n  }\n}\n```\n\n---\n\n## 🔧 Configuration Reference\n\nAll configuration parameters can be supplied via environment variables or CLI arguments. **`SWAGGER_MCP_SPEC_URL` is the only required parameter.**\n\n| Environment Variable | CLI Argument | Required | Default | Description |\n|---|---|---|---|---|\n| `SWAGGER_MCP_SPEC_URL` | `--spec-url` | Yes | — | Swagger/OpenAPI spec URL |\n| `SWAGGER_MCP_BASE_URL` | `--base-url` | No | Auto-derived | Override target API base URL |\n| `SWAGGER_MCP_BEARER_TOKEN` | `--bearer-token` | No | — | Bearer token for `Authorization: Bearer <token>` |\n| `SWAGGER_MCP_API_KEY` | `--api-key` | No | — | API Key header value |\n| `SWAGGER_MCP_API_KEY_HEADER` | `--api-key-header` | No | `X-API-Key` | Custom header name for API Key |\n| `SWAGGER_MCP_BASIC_USER` | `--basic-user` | No | — | Username for Basic Auth |\n| `SWAGGER_MCP_BASIC_PASS` | `--basic-pass` | No | — | Password for Basic Auth |\n| `SWAGGER_MCP_TIMEOUT` | `--timeout` | No | `30000` | HTTP request timeout in milliseconds |\n| `SWAGGER_MCP_HEADERS` | `--headers` | No | `{}` | Extra HTTP headers as JSON string |\n\n---\n\n### 🔑 Authentication Examples\n\nMultiple authentication methods can be set simultaneously:\n\n```bash\n# Bearer Token\nSWAGGER_MCP_BEARER_TOKEN=sk-your-token-here\n\n# API Key (Custom Header)\nSWAGGER_MCP_API_KEY=your-api-key\nSWAGGER_MCP_API_KEY_HEADER=X-Custom-Key\n\n# Basic Auth\nSWAGGER_MCP_BASIC_USER=admin\nSWAGGER_MCP_BASIC_PASS=secret123\n```\n\n> [!NOTE]\n> If both Bearer and Basic Auth are specified, Basic Auth will overwrite the `Authorization` header. Combine Bearer Token with API Key headers if multiple headers are required.\n\n---\n\n## 🏷️ Tool Naming Strategy\n\nEndpoints from your OpenAPI spec are converted into MCP tools using the following priority order:\n\n| Priority | Source | Example |\n|---|---|---|\n| **1st** | `operationId` defined in spec | `getUserById` |\n| **2nd** | Tag + Method + Path | `users_get_by_id` |\n| **3rd** | Method + Path | `get_api_v1_users_by_id` |\n\n---\n\n## 🧰 Built-in Meta Tools\n\n| Tool | Description |\n|---|---|\n| `_swagger_mcp_reload` | Re-fetches and parses the Swagger spec live. Useful when developing or updating APIs without restarting the server. |\n\n---\n\n## 📁 Project Structure\n\n```text\nswagger-mcp/\n├── package.json\n├── tsconfig.json\n├── src/\n│   ├── index.ts              # Entry point & CLI argument parser\n│   ├── server.ts             # MCP server initialization & tool registration\n│   ├── swagger-parser.ts     # OpenAPI 2.0/3.x spec fetcher & parser\n│   ├── tool-builder.ts       # Converts OpenAPI operations -> JSON Schema tools\n│   ├── request-handler.ts    # Proxies MCP tool calls to HTTP endpoints\n│   ├── auth.ts               # Authentication header builder\n│   ├── config.ts             # Environment & CLI configuration manager\n│   └── types.ts              # Shared TypeScript interfaces\n└── dist/                     # Compiled JavaScript output\n```\n\n---\n\n## 📄 License\n\n[MIT](LICENSE)","readmeFilename":"README.md"}