Swagger Explorer MCP

A Management Control Plane (MCP) server for exploring and analyzing Swagger/OpenAPI specifications through Claude.

Quick Start

Install and run globally using npx:

Or install with environment variables:

Installation for Claude Desktop

1. Open Claude Desktop

2. Click on Settings (gear icon)

3. Select "Tools & Integrations"

4. Click "Add MCP Server"

5. Enter the following:

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

6. Click "Install"

Usage with Claude

Here are some example interactions with Claude:

Basic Swagger Exploration

Analyzing Specific Endpoints

Schema Analysis

Features

1. Authentication Support

   • Bearer token authentication

   • Configurable through environment variables

2. Custom Response Formatting

   • Minimal format: Removes null/empty values

   • Detailed format: Includes metadata and timestamps

   • Raw format: Unmodified response

3. Schema Analysis

   • Detailed property exploration

   • Response schema analysis

   • Schema relationships

4. API Exploration

   • Path listing

   • Method filtering

   • Response format analysis

Configuration

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

Get Schema Details

Get Response Schemas

Response Formats

Minimal Format

Detailed Format

Common Use Cases

1. API Documentation Review

   Human: Can you summarize all the available endpoints and their purposes?

2. Schema Validation

   Human: What fields are required for creating a new pet?

3. Response Analysis

   Human: What are the possible error responses for the login endpoint?

4. Integration Planning

   Human: How should I structure my request to create a new order?

Troubleshooting

1. Connection Issues

   • Ensure the Swagger URL is accessible

   • Check if authentication token is correct

   • Verify port is not in use

2. Authorization Errors

   • Verify AUTH_TOKEN is set correctly

   • Ensure bearer token is included in requests

3. Schema Not Found

   • Check if schema name is exact match

   • Verify Swagger spec is loaded correctly

Security Notes

1. The MCP requires authentication if AUTH_TOKEN is set

2. All requests are logged for debugging

3. Sensitive information is not cached

4. Rate limiting is applied to prevent abuse

Development

To contribute or modify:

1. Clone the repository

2. Install dependencies:

   npm install

3. Build:

   npm run build

4. Run locally:

   npm start

License

MIT License - See LICENSE file for details