swagger-mcp

The Problem

Your AI assistant can write code, debug logic, and look up documentation, but the moment you ask it about your internal REST API, it hallucinates endpoints and makes up field names. The spec exists; the AI just can't see it.

What It Does

swagger-mcp is an MCP server that reads any Swagger/OpenAPI definition and exposes it to AI clients as structured, queryable tools. Point it at your API spec, connect your AI assistant, and you can explore endpoints, inspect schemas, generate Go scaffolding, or proxy live requests, instantly.

How It Works

swagger-mcp parses your OpenAPI spec and registers a set of MCP tools the AI can call directly:

• listEndpoints: enumerate all routes with HTTP methods and summaries
• listEndpointModels: fetch request/response schemas for a specific route
• generateModelCode: emit a Go struct for any schema model
• generateEndpointToolCode: scaffold a Go MCP tool handler for an endpoint
• generateServer: generate a complete, runnable Go MCP server project

In proxy mode (--proxy-mode), every Swagger endpoint is dynamically registered as a callable MCP tool. The server forwards each AI tool invocation as a live HTTP request to your real API, with anti-hallucination guards baked in to prevent the model from fabricating response data.

Features

• 🔌 Three transport modes: stdio (Cursor, Claude Desktop), sse, and streamable-http
• 🚦 Endpoint filtering: include/exclude paths and HTTP methods via regex
• 🔐 Full auth support: API Key, Bearer/JWT, Basic Auth, OAuth2 client credentials
• 🛠️ CLI inspection: inspect endpoints, inspect endpoint, inspect security, inspect models
• 🏗️ Go code generation: structs, tool handlers, and complete server scaffolding
• 📦 Smart spec caching: specs cached locally with ETag/Last-Modified revalidation
• 🖥️ Built-in web UI: interactive dashboard for manual tool testing
• 🗂️ Per-project config: .swagger-mcp file sets spec location per directory

Installation

# Build from source
git clone https://github.com/caioreix/swagger-mcp.git
cd swagger-mcp
make build   # → build/swagger-mcp

# Or with Docker
docker build -t swagger-mcp .

Usage

Connect Cursor to any API in 30 seconds:

./build/swagger-mcp --swagger-url="https://petstore.swagger.io/v2/swagger.json"

In Cursor → Settings → Features → MCP → + Add New MCP Server:

Field	Value
Transport	stdio
Command	/path/to/swagger-mcp --swagger-url=https://your-api/swagger.json

Proxy mode: every endpoint becomes a live tool:

./build/swagger-mcp --proxy-mode \
  --swagger-url="https://your-api/swagger.json" \
  --include-paths="^/v2/.*" \
  --exclude-methods="DELETE"

Authenticate with environment variables:

BEARER_TOKEN=my-jwt ./build/swagger-mcp --proxy-mode \
  --swagger-url="https://your-api/swagger.json"

Configuration

Flag	Env Variable	Description
--swagger-url	SWAGGER_MCP_SWAGGER_URL	URL of the Swagger/OpenAPI definition
--transport	SWAGGER_MCP_TRANSPORT	stdio, sse, or streamable-http
--port	SWAGGER_MCP_PORT	HTTP port for SSE/StreamableHTTP (default: 8080)
--proxy-mode	SWAGGER_MCP_PROXY_MODE	Dynamic proxy: each endpoint becomes an MCP tool
--base-url	SWAGGER_MCP_BASE_URL	Override the base URL from the spec
--include-paths	SWAGGER_MCP_INCLUDE_PATHS	Regex patterns for paths to expose
--exclude-paths	SWAGGER_MCP_EXCLUDE_PATHS	Regex patterns for paths to hide
--include-methods	SWAGGER_MCP_INCLUDE_METHODS	HTTP methods to expose: GET,POST
--exclude-methods	SWAGGER_MCP_EXCLUDE_METHODS	HTTP methods to hide: DELETE,PUT
--ui	SWAGGER_MCP_UI	Enable the built-in web UI

---

Give your AI assistant eyes on your API: grab swagger-mcp on GitHub.