This Swagger MCP Server reads the backend API's OpenAPI/Swagger specification, parses and stores endpoints, request/response schemas, and error codes, and exposes a set of MCP tools that Claude Code can use to discover APIs by keyword, inspect details, and generate AI-friendly DTOs and networking code. The core tools you can invoke are searchApiByKeyword, getApiDetail, getRequestFormat, getResponseFormat, and getErrorFormats. For example, you can search for endpoints related to authentication, retrieve a detailed API definition (including request body, response formats, and error mappings), and obtain AI-ready representations of requests and responses to drive automatic code generation in Kotlin or Swift. This enables natural-language API queries like “find login API and create DTOs” and immediate generation of client code by the AI system. The server synchronizes Swagger metadata into MySQL and provides a structured API for Claude Code to consume, including example payloads to accelerate code generation.

Prerequisites:

• Docker installed and running
• Optional: Java 21 and Gradle if you want to run locally without Docker

Option A: Run via Docker (recommended)

1. Build or pull the MCP server image (example): docker build -t woojjam-swagger-mcp-server-image . # if you have a Dockerfile, or pull from registry

   or use a pre-published image

2. Run the container (as a background service): docker run -d --name swagger-mcp-server -p 8080:8080 -e MCP_ACCESS_TOKEN=YOUR_TOKEN woojjam-swagger-mcp-server-image
3. Verify the MCP endpoint is reachable: curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:8080/mcp

Option B: Run locally without Docker (Java/Gradle)

1. Prerequisites: Java 21, Gradle
2. Clone repository and navigate to project root
3. Build and run locally: ./gradlew bootRun
4. Access MCP endpoint (default port 8080): http://localhost:8080/mcp

Environment variables (examples):

• MCP_ACCESS_TOKEN: token used to authorize MCP calls
• APP_IMAGE: optional, if you customize the runtime image

Notes:

• If using Docker, ensure the container exposes the MCP endpoint (commonly /mcp).
• The .env file (if you use Docker with compose) should include database credentials if you enable local MySQL.

Tips and known considerations:

• Ensure your Swagger/OpenAPI document is reachable from the MCP server (CORS and network access may affect fetching the API spec).
• If $ref schemas do not resolve, verify that all components/schemas referenced in the OpenAPI document are present and properly defined.
• The MCP tools return AI-friendly structures with explicit field types and examples to support immediate code generation; ensure your OpenAPI definitions include representative examples for best results.
• For production deployments, configure a persistent MySQL database and set proper MCP_ACCESS_TOKEN scopes.
• When using Docker, consider mounting a volume for the DB to preserve metadata across restarts.