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

| Tool | Description | | ---------------------- | ------------------------------------------------------------------- | | swagger_load_spec | Load a Swagger/OpenAPI spec from URL, parse and cache it | | swagger_update_cache | Re-fetch spec and rebuild cache | | swagger_get_info | Get API metadata (title, version, servers, auth schemes) | | swagger_list_tags | List all tags with endpoint counts | | swagger_list_paths | List endpoints with filtering (tag, method, keyword) and pagination | | swagger_get_endpoint | Get endpoint summary + cached file path for full details | | swagger_list_schemas | List schema definitions with filtering and pagination | | swagger_get_schema | Get schema summary + cached file path for full definition | | swagger_search | Search across endpoints and schemas by keyword | | swagger_call_api | Execute HTTP requests with 2-phase confirmation | | swagger_set_auth | Dynamically set or clear the Authorization header at runtime |

Prompts

| Prompt | Arguments | Description | | ------------------------ | ---------------- | -------------------------------------------------------------- | | swagger_explore_api | url | Guided workflow to load and fully explore an API spec | | swagger_find_endpoint | keyword | Search for endpoints by keyword and view full details | | swagger_integrate_api | url, task | Find the right endpoint for a task and execute an API call |

Resources

| Resource | URI | Description | | ---------------- | ------------------------- | ---------------------------------------------------- | | api-info | swagger://api/info | API basic information (title, version, servers, auth) | | api-endpoints | swagger://api/endpoints | Index of all API endpoints | | api-schemas | swagger://api/schemas | Index of all schema/model definitions |

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

| Variable | Default | Description | | -------------------- | ---------------- | ------------------------------------------------------------------------------------- | | SWAGGER_URL | (empty) | Auto-load spec on startup | | TRANSPORT | stdio | Transport mode: stdio or http | | MCP_PORT | 3000 | HTTP server port | | MCP_HOST | 0.0.0.0 | HTTP server host | | API_BASE_URL | (empty) | Override API base URL for calls | | API_AUTH_TOKEN | (empty) | Initial Authorization header value (can be updated at runtime via swagger_set_auth) | | CACHE_DIR | .swagger-cache | Custom cache directory path | | SESSION_TIMEOUT_MS | 1800000 | HTTP session timeout (30 min) | | MAX_SESSIONS | 100 | Max concurrent HTTP sessions |

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