Swagger Explorer

🚀 Swagger Explorer MCP Server

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

🚀 Quick Start

Install and run globally using npx:

npx -y @johnneerdael/swagger-mcp

Or install via environment variables:

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

📦 Installation Instructions for Claude Desktop Users

1. Open the Tools and Integrations menu.
2. Click the "Add MCP Server" button.
3. Enter the following configuration:
   • Address: localhost
   • Port: 3000
4. After completion, the MCP server will run automatically.

💻 Usage Examples

Basic Usage

Claude: Can you list all available API endpoints for me through the Swagger interface?
You: Sure! Please provide the Swagger URL.

Advanced Usage

Claude: What's the data format returned by the GET /users endpoint?
You: Let me check the Swagger documentation. This endpoint returns an object containing user information, including ID, username, and email.

✨ Features

1. Authentication Support: Authenticate via bearer tokens.
2. Customizable Response Formats: Support both Minimal and Detailed response modes.
3. Schema Analysis: Automatically parse and display the structure of API interfaces.
4. API Exploration: Provide full API documentation browsing capabilities.

📚 Documentation

Configuration Instructions

1. Environment Variable Settings
   • BASE_URL: The base URL of the service, defaulting to /api.
   • AUTH_TOKEN: The access token for authentication.
   • PORT: The port on which the service runs, defaulting to 3000.
   • SWAGGER_URL: The URL address of the Swagger documentation.

API Endpoint Usage Instructions

Explore API

curl http://localhost:3000/explore \
  -H "Authorization: Bearer your-token"

Get Schema Details

curl http://localhost:3000/schema-details \
  -H "Authorization: Bearer your-token" \
  -d '{"schemaName":"User"}'

Get Response Schemas

curl http://localhost:3000/response-schemas \
  -H "Authorization: Bearer your-token"

Response Formats

Minimal Mode

{
  "status": "success",
  "data": {}
}

Detailed Mode

{
  "status": "success",
  "data": {},
  "description": "Complete API interface documentation"
}

Common Use Cases

1. Explore and analyze API endpoints.
2. Get detailed information about specific schemas.
3. Analyze and validate response formats.

Troubleshooting

1. Connection Issues
   • Ensure the Swagger URL is available.
   • Check if the token is correct.
   • Verify that the port is not occupied.
2. Authorization Errors
   • Confirm that the AUTH_TOKEN is set correctly.
   • Include the bearer token in the request.
3. Schema Not Found
   • Check if the schema name is accurate.
   • Ensure that the Swagger specification is loaded correctly.

Security Precautions

1. The MCP requires authentication. If AUTH_TOKEN is set, it must be provided.
2. All requests are logged for debugging purposes.
3. Sensitive information is not cached.
4. Rate limiting is implemented to prevent abuse.

Development Instructions

1. Clone the repository:

git clone [repository address]

2. Install dependencies:

npm install

3. Build the project:

npm run build

4. Run locally:

npm start

📄 License

This project is under the MIT License - see the LICENSE file for details.