Swagger API MCP Server

English | 中文

An MCP (Model Context Protocol) server that parses Swagger 2.0 and OpenAPI 3.x specifications, exposing API structure through MCP tools. Features a local file-cache architecture that reduces token usage by 85-95% compared to inline responses.

Features

• Swagger 2.0 & OpenAPI 3.x — Full dual-format support
• Smart Caching — Spec parsed once, stored as local JSON files; tools return compact summaries + file paths (~200 chars vs 5-20KB)
• 11 MCP Tools — Load, browse, search, call APIs, and manage auth dynamically
• 3 MCP Prompts — Guided workflows for exploring, searching, and integrating APIs
• 3 MCP Resources — Direct access to cached API info, endpoints, and schemas
• Two Transport Modes — stdio (for CLI/IDE integration) and HTTP (for multi-session web use)
• 2-Phase API Calls — Preview requests before executing them
• Zero External Parsers — Custom $ref resolver with circular reference protection

Prerequisites

• Node.js >= 24

Quick Start

Install from npm

npm install -g swagger-api-mcp-server

Or clone and build

git clone https://github.com/NekoTarou/swagger-api-mcp-server.git
cd swagger-api-mcp-server
npm install
npm run build

Run

# stdio mode (default) — for MCP clients like Claude Desktop
npm start

# Auto-load a spec on startup
SWAGGER_URL=https://petstore.swagger.io/v2/swagger.json npm start

# HTTP mode — multi-session with Express
npm run start:http

MCP Client Configuration

Claude Desktop

Add to your Claude Desktop config file (claude_desktop_config.json):

{
  "mcpServers": {
    "swagger-api": {
      "command": "npx",
      "args": ["-y", "swagger-api-mcp-server"],
      "env": {
        "SWAGGER_URL": "https://petstore.swagger.io/v2/swagger.json"
      }
    }
  }
}

Cursor / VS Code

Add to your MCP settings:

{
  "mcpServers": {
    "swagger-api": {
      "command": "npx",
      "args": ["-y", "swagger-api-mcp-server"],
      "env": {
        "SWAGGER_URL": "https://your-api.example.com/openapi.json"
      }
    }
  }
}

Tools

Prompts

Resources

Cache Architecture

When a spec is loaded, it's parsed once and stored as structured JSON files:

.swagger-cache/
├── meta.json              # Cache metadata (URL, counts, timestamp)
├── info.json              # Full API info (title, servers, auth)
├── tags.json              # Tag list with endpoint counts
├── paths-index.json       # Endpoint index for fast lookup
├── schemas-index.json     # Schema index for fast lookup
├── endpoints/             # One file per endpoint (deep-resolved)
│   └── GET__users__{id}.json
└── schemas/               # One file per schema (deep-resolved)
    └── User.json

Tools return brief summaries with file paths. The LLM reads full details on demand via the Read tool — saving 85-95% of tokens per call.

Environment Variables

Development

npm run dev            # Dev mode with auto-reload (tsx watch)
npm test               # Run tests
npm run build          # TypeScript compilation → dist/
npm run clean          # Remove dist/

License

MIT