swagger-mcp

A read-only Model Context Protocol server for navigating an OpenAPI / Swagger specification. It gives a coding agent tools to explore a large API's documentation — search endpoints, read parameters and schemas, inspect auth — without dumping the whole spec into context.

It never calls the described API. It only reads its documentation.

Works with any MCP-capable harness (Claude Code, Cursor, Cline, Windsurf, Zed, opencode, …) over stdio.

Usage

Add it to your MCP client config. No install step — npx fetches it on demand:

{
  "mcpServers": {
    "swagger-mcp": {
      "command": "npx",
      "args": ["-y", "@emreyc/swagger-mcp@latest"]
    }
  }
}

Every tool takes a spec parameter — a URL (or local path) to a Swagger 2.0 or OpenAPI 3.x document — so a single server can navigate any number of specs in one session. Internal/localhost URLs (e.g. Spring Boot's http://localhost:8080/v3/api-docs) are supported.

If you mostly work with one spec, set API_DOCS_URL as a default so spec can be omitted:

{
  "mcpServers": {
    "swagger-mcp": {
      "command": "npx",
      "args": ["-y", "@emreyc/swagger-mcp@latest"],
      "env": { "API_DOCS_URL": "https://api.example.com/swagger.json" }
    }
  }
}

Specs are fetched lazily and cached per URL for the process lifetime.

Tools

Designed for progressive disclosure — orient, then discover, then drill down — so the agent loads only what it needs.

Tool	Purpose
get_api_overview	Title, version, servers, global security, counts. Start here.
list_tags	Tags (logical groups) with endpoint counts.
list_endpoints	Compact index of endpoints; optional tag filter.
search_endpoints	Substring search over path/summary/description/params.
list_schemas	Named schemas with one-line descriptions.
search_schemas	Substring search over schema names, fields, descriptions.
get_endpoint	Full detail for one method+path: params, request/response schemas, auth.
get_schema	Resolve one named schema.
get_auth	Security schemes in full (OAuth2 flows, scopes, API-key locations).

Every tool also accepts an optional spec argument (a spec URL or path); when omitted it falls back to API_DOCS_URL.

Swagger 2.0 and OpenAPI 3.x are normalized into one consistent output shape. Nested named schemas are shown as { "$schema": "Name" } markers — call get_schema to expand them. This keeps every response bounded and is safe with circular schemas.

Development

npm install
npm run typecheck
npm test
npm run build

License

MIT