@abhishekkumar00019/swagger-mcp

A dynamic Model Context Protocol (MCP) server that converts any Swagger 2.0 or OpenAPI 3.x specification into callable MCP tools on the fly.

Point 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.

---

✨ Features

• 🔄 Dynamic Tool Generation — Automatically parses Swagger 2.0 & OpenAPI 3.x specs at startup.
• 🛠️ Zero Boilerplate — Give it a spec URL and every endpoint is instantly exposed as an MCP tool.
• 🔐 Flexible Auth Support — Bearer Tokens, API Keys, and Basic Auth configured effortlessly via env vars or CLI flags.
• 🌐 Smart Base URL Resolution — Auto-derives base URL from config → spec server definition → spec origin URL.
• 🔁 Hot Reloading — Re-fetch and re-parse the spec live at runtime using the _swagger_mcp_reload tool.
• 📝 Rich Schemas & Descriptions — Translates OpenAPI parameters and request bodies into strict JSON schemas for precise LLM tool calling.
• ⏱️ Configurable Timeouts & Custom Headers — Easily set custom request headers and request timeout thresholds.

---

🚀 Quick Start

Option A: Direct via npx (No Installation Required)

SWAGGER_MCP_SPEC_URL=https://petstore.swagger.io/v2/swagger.json npx @abhishekkumar00019/swagger-mcp

Option B: Global NPM Installation

npm install -g @abhishekkumar00019/swagger-mcp

SWAGGER_MCP_SPEC_URL=https://petstore.swagger.io/v2/swagger.json swagger-mcp

Option C: Local Repository Setup

1. Clone & Install Dependencies:

   git clone https://github.com/itachiuchihadev/swagger-mcp.git
   cd swagger-mcp
   npm install
   

2. Build the Project:

   npm run build
   

3. Run locally:

   SWAGGER_MCP_SPEC_URL=https://petstore.swagger.io/v2/swagger.json node dist/index.js
   

---

⚙️ MCP Client Configurations

Below are sample configurations for popular MCP clients using npx @abhishekkumar00019/swagger-mcp.

1. Claude Desktop

Add to your claude_desktop_config.json:

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

{
  "mcpServers": {
    "swagger-mcp": {
      "command": "npx",
      "args": ["-y", "@abhishekkumar00019/swagger-mcp"],
      "env": {
        "SWAGGER_MCP_SPEC_URL": "https://petstore.swagger.io/v2/swagger.json",
        "SWAGGER_MCP_BEARER_TOKEN": "your-api-token-here"
      }
    }
  }
}

---

2. Claude Code (CLI)

Add directly via the Claude Code CLI:

claude mcp add swagger-mcp -- npx -y @abhishekkumar00019/swagger-mcp --spec-url https://petstore.swagger.io/v2/swagger.json

Or add to .mcp.json in your project root:

{
  "mcpServers": {
    "swagger-mcp": {
      "command": "npx",
      "args": ["-y", "@abhishekkumar00019/swagger-mcp"],
      "env": {
        "SWAGGER_MCP_SPEC_URL": "https://petstore.swagger.io/v2/swagger.json"
      }
    }
  }
}

---

3. GitHub Copilot / VS Code

Add to .vscode/mcp.json in your workspace or global VS Code settings:

{
  "mcpServers": {
    "swagger-mcp": {
      "command": "npx",
      "args": ["-y", "@abhishekkumar00019/swagger-mcp"],
      "env": {
        "SWAGGER_MCP_SPEC_URL": "https://petstore.swagger.io/v2/swagger.json",
        "SWAGGER_MCP_API_KEY": "your-api-key"
      }
    }
  }
}

---

4. Cursor

Add to .cursor/mcp.json or configure in Cursor Settings → Features → MCP:

{
  "mcpServers": {
    "swagger-mcp": {
      "command": "npx",
      "args": ["-y", "@abhishekkumar00019/swagger-mcp"],
      "env": {
        "SWAGGER_MCP_SPEC_URL": "https://petstore.swagger.io/v2/swagger.json"
      }
    }
  }
}

---

5. Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "swagger-mcp": {
      "command": "npx",
      "args": ["-y", "@abhishekkumar00019/swagger-mcp"],
      "env": {
        "SWAGGER_MCP_SPEC_URL": "https://petstore.swagger.io/v2/swagger.json"
      }
    }
  }
}

---

6. Roo Code / Cline (VS Code Extension)

Add to cline_mcp_settings.json (or roo_code_mcp_settings.json):

{
  "mcpServers": {
    "swagger-mcp": {
      "command": "npx",
      "args": ["-y", "@abhishekkumar00019/swagger-mcp"],
      "env": {
        "SWAGGER_MCP_SPEC_URL": "https://petstore.swagger.io/v2/swagger.json"
      }
    }
  }
}

---

7. ChatGPT & OpenAI (Custom GPTs / Assistants / API)

Direct OpenAPI Spec Import (Native Custom GPT Actions): ChatGPT 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.

Via MCP HTTP/SSE Gateway: If 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:

npx supergateway --stdio "npx -y @abhishekkumar00019/swagger-mcp --spec-url https://petstore.swagger.io/v2/swagger.json" --port 8000

---

8. Zed Editor

Add to ~/.config/zed/settings.json:

{
  "context_servers": {
    "swagger-mcp": {
      "command": {
        "path": "npx",
        "args": ["-y", "@abhishekkumar00019/swagger-mcp"]
      },
      "env": {
        "SWAGGER_MCP_SPEC_URL": "https://petstore.swagger.io/v2/swagger.json"
      }
    }
  }
}

---

🔧 Configuration Reference

All configuration parameters can be supplied via environment variables or CLI arguments. SWAGGER_MCP_SPEC_URL is the only required parameter.

Environment Variable	CLI Argument	Required	Default	Description
SWAGGER_MCP_SPEC_URL	--spec-url	Yes	—	Swagger/OpenAPI spec URL
SWAGGER_MCP_BASE_URL	--base-url	No	Auto-derived	Override target API base URL
SWAGGER_MCP_BEARER_TOKEN	--bearer-token	No	—	Bearer token for Authorization: Bearer <token>
SWAGGER_MCP_API_KEY	--api-key	No	—	API Key header value
SWAGGER_MCP_API_KEY_HEADER	--api-key-header	No	X-API-Key	Custom header name for API Key
SWAGGER_MCP_BASIC_USER	--basic-user	No	—	Username for Basic Auth
SWAGGER_MCP_BASIC_PASS	--basic-pass	No	—	Password for Basic Auth
SWAGGER_MCP_TIMEOUT	--timeout	No	30000	HTTP request timeout in milliseconds
SWAGGER_MCP_HEADERS	--headers	No	{}	Extra HTTP headers as JSON string

---

🔑 Authentication Examples

Multiple authentication methods can be set simultaneously:

# Bearer Token
SWAGGER_MCP_BEARER_TOKEN=sk-your-token-here

# API Key (Custom Header)
SWAGGER_MCP_API_KEY=your-api-key
SWAGGER_MCP_API_KEY_HEADER=X-Custom-Key

# Basic Auth
SWAGGER_MCP_BASIC_USER=admin
SWAGGER_MCP_BASIC_PASS=secret123

[!NOTE] 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.

---

🏷️ Tool Naming Strategy

Endpoints from your OpenAPI spec are converted into MCP tools using the following priority order:

Priority	Source	Example
1st	operationId defined in spec	getUserById
2nd	Tag + Method + Path	users_get_by_id
3rd	Method + Path	get_api_v1_users_by_id

---

🧰 Built-in Meta Tools

Tool	Description
_swagger_mcp_reload	Re-fetches and parses the Swagger spec live. Useful when developing or updating APIs without restarting the server.

---

📁 Project Structure

swagger-mcp/
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts              # Entry point & CLI argument parser
│   ├── server.ts             # MCP server initialization & tool registration
│   ├── swagger-parser.ts     # OpenAPI 2.0/3.x spec fetcher & parser
│   ├── tool-builder.ts       # Converts OpenAPI operations -> JSON Schema tools
│   ├── request-handler.ts    # Proxies MCP tool calls to HTTP endpoints
│   ├── auth.ts               # Authentication header builder
│   ├── config.ts             # Environment & CLI configuration manager
│   └── types.ts              # Shared TypeScript interfaces
└── dist/                     # Compiled JavaScript output

---

📄 License

MIT