Swagger Explorer MCP server for AI agents

The Swagger Explorer MCP is a server that enables Claude to explore and analyze OpenAPI specifications, allowing for interactive review of API documentation. It helps users understand API endpoints, request/response structures, and schema details directly through Claude's interface.

Quick Start

Install and run globally using npx:

npx -y @johnneerdael/swagger-mcp

Or install with environment variables:

npx -y @johnneerdael/swagger-mcp \
  --env BASE_URL=/api \
  --env AUTH_TOKEN=your-token \
  --env PORT=3000

Setting Up in Claude Desktop

Open Claude Desktop
Click on Settings (gear icon)
Select "Tools & Integrations"
Click "Add MCP Server"

Enter the following:

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

Click "Install"

Using with Claude

Here are some example interactions to try:

Basic Swagger Exploration

Human: Can you explore the Swagger documentation at http://localhost:8080/docs?

Claude: I'll help you explore that Swagger documentation using the Swagger Explorer MCP.

Let me analyze the API endpoints and schemas for you:

[Claude would then use the MCP to fetch and analyze the Swagger documentation]

Analyzing Specific Endpoints

Human: What are the available response schemas for the /pets POST endpoint?

Claude: I'll check the response schemas for that endpoint using the MCP.

[Claude would use the MCP to fetch specific endpoint details]

Schema Analysis

Human: Can you show me the detailed structure of the Pet schema?

Claude: I'll retrieve the detailed schema information using the MCP.

[Claude would use the MCP to analyze the schema structure]

Features

Authentication Support: Bearer token authentication configurable through environment variables
Custom Response Formatting: Options for minimal, detailed, or raw response formats
Schema Analysis: Explore properties, relationships, and response schemas
API Exploration: List paths, filter methods, and analyze response formats

Configuration Options

The MCP server can be configured using these environment variables:

BASE_URL: Base path for the API (default: '')
AUTH_TOKEN: Bearer token for authentication
PORT: Server port (default: 3000)
SWAGGER_URL: Default Swagger documentation URL

API Endpoints

Explore API

curl -X POST http://localhost:3000/api/explore \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "http://your-swagger-url",
    "options": {
      "paths": true,
      "schemas": true
    }
  }'

Get Schema Details

curl -X POST http://localhost:3000/api/schema-details \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "http://your-swagger-url",
    "schemaName": "Pet"
  }'

Get Response Schemas

curl -X POST http://localhost:3000/api/response-schemas \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "http://your-swagger-url",
    "path": "/pets",
    "method": "post"
  }'

Response Formats

Minimal Format

{
  "status": "success",
  "data": {
    // Only non-null values
  }
}

Detailed Format

{
  "status": "success",
  "timestamp": "2025-01-29T10:00:00.000Z",
  "data": {
    // Full response
  },
  "metadata": {
    "version": "1.0",
    "format": "detailed"
  }
}

Common Use Cases

API Documentation Review: Ask Claude to summarize all available endpoints and their purposes
Schema Validation: Inquire about required fields for specific operations
Response Analysis: Explore possible error responses for endpoints
Integration Planning: Get guidance on how to structure API requests

Troubleshooting

Connection Issues

Ensure the Swagger URL is accessible
Check if authentication token is correct
Verify port is not in use

Authorization Errors

Verify AUTH_TOKEN is set correctly
Ensure bearer token is included in requests

Schema Not Found

Check if schema name is exact match
Verify Swagger spec is loaded correctly

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "swagger-explorer" '{"command":"npx","args":["-y","@johnneerdael/swagger-mcp"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect