home / mcp / swagger explorer mcp server

Swagger Explorer MCP Server

Provides an MCP server to explore and analyze Swagger/OpenAPI specifications through Claude or other MCP clients.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "johnneerdael-swagger-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@johnneerdael/swagger-mcp",
        "--swagger-url=$SWAGGER_URL"
      ],
      "env": {
        "PORT": "3000",
        "BASE_URL": "''",
        "AUTH_TOKEN": "YOUR_TOKEN",
        "SWAGGER_URL": "URL_TO_SWAGGER"
      }
    }
  }
}

You can explore and analyze Swagger/OpenAPI specifications through Claude by using the Swagger Explorer MCP server. It connects to a Swagger URL, analyzes endpoints and schemas, and presents structured insights that help you understand APIs faster.

How to use

Use the Swagger Explorer MCP with your preferred MCP client to connect to a Swagger URL and request exploration, schema details, or response schemas. Start a session by pointing the MCP to the target Swagger documentation and optionally enable path and schema analysis to tailor the results to your needs.

Typical actions you can perform include exploring the API surface (paths and methods), inspecting detailed schemas for entities like Pet, and retrieving response schemas for specific endpoints. The MCP handles authentication when a token is provided and formats results according to your chosen output mode.

How to install

Prerequisites: you need Node.js installed on your machine to run MCPs via npx or npm.

# Quick start: run globally with npx
npx -y @johnneerdael/swagger-mcp

Install with environment variables to specify the base API URL, authentication, and port.

# Install with environment variables
npx -y @johnneerdael/swagger-mcp \
  --env BASE_URL=/api \
  --env AUTH_TOKEN=your-token \
  --env PORT=3000

If you are integrating with Claude Desktop, add the MCP server using the following settings.

Name: Swagger Explorer
Command: npx -y @johnneerdael/swagger-mcp
Arguments: --swagger-url=$SWAGGER_URL

Configuration and usage details

Environment variables you can configure include the base URL, bearer token, port, and the default Swagger documentation URL. These are used to control how the MCP connects to and authenticates with the Swagger source.

The MCP supports a minimal, detailed, or raw response format. Choose the format that best fits your workflow.

Troubleshooting

If you encounter connection issues, verify that the Swagger URL is accessible and the authentication token (if used) is correct. Ensure the server port is not in use by another process.

For authorization errors, confirm that AUTH_TOKEN is set correctly and that bearer tokens are included in requests.

If a schema cannot be found, double-check the exact schema name and confirm that the Swagger specification loaded successfully.

Security notes

The MCP requires authentication if an AUTH_TOKEN is configured. All requests are logged for debugging, and sensitive information is not cached. Rate limiting helps prevent abuse.

Development

To contribute or modify: clone the project, install dependencies, build, and run locally.

npm install

npm run build

npm start

License

MIT License - See the license file for details.

Available tools

Explore API

Fetches and lists API endpoints, schemas, and metadata from the Swagger documentation.

Get Schema Details

Retrieves detailed information for a specified schema name from the Swagger spec.

Get Response Schemas

Returns the response schemas for a given path and HTTP method.