Swagger MCP Multi-API Server

You can run and use the Swagger MCP Multi-API Edition to automatically understand and interact with multiple Swagger/OpenAPI definitions from a single MCP server. This setup lets you list APIs, inspect endpoints, view models, and generate TypeScript code for models and MCP tools, while caching definitions for fast access.

How to use

You interact with the MCP server through your MCP client. Start by configuring one or more APIs in the apis.yaml file inside your project’s .cursor folder. Then run the MCP server using your preferred method (local Docker, Docker Compose, or a local node-based run). Once the server is running, you can request the list of APIs, drill into endpoints for a specific API, inspect the models used by an endpoint, and generate TypeScript interfaces or MCP tool definitions from the results. Use these capabilities to automate integration with multiple Swagger definitions from a single place.

How to install

Prerequisites you need before installing: Node.js version 20 or newer, and either npm or pnpm for package management.

# Dependency install (local development)
npm install

# TypeScript build
npm run build

# Local server start
node build/index.js

Additional configuration and usage notes

Configure multiple APIs in a single MCP server by creating an apis.yaml file inside the .cursor folder of your project. Each API entry should include a name, a description, and a URL to its Swagger document.

The repository provides an example mcp.json configuration that maps a local .cursor/apis.yaml into the MCP container. Use a Docker driver to run the server, or use Docker Compose for orchestration. Ensure the path to apis.yaml in the mount matches your project structure.

You can also run the server with Docker by building the image and executing a container that references your apis.yaml. This approach is convenient for testing and quick iteration.

{
  "mcpServers": {
    "api-docs": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/to/your/project/.cursor/apis.yaml:/app/apis.yaml:ro",
        "swagger-mcp-multi:latest"
      ]
    }
  }
}

Security and data handling

Apis.yaml may contain sensitive API URLs. Store this file securely and add it to your .gitignore to prevent accidental exposure in version control.

Troubleshooting tips

If you cannot see APIs or endpoints, verify that apis.yaml is mounted correctly into the MCP container and that each API entry includes a valid URL to a Swagger document.

Notes on local development

For local development, you can run the server with npm-based workflows or Docker Compose. The Docker Compose workflow starts services in the background and lets you tail logs to monitor activity.

Available tools

listApis

List all configured APIs with their descriptions and URLs.

listEndpoints

Retrieve all endpoints for a specified API, including paths and HTTP methods.

listEndpointModels

Show the models used by a specific API endpoint, identified by path and HTTP method.

generateModelCode

Generate TypeScript interfaces for a given API model.

generateEndpointToolCode

Create MCP tool definitions for a specified endpoint.

version

Return the MCP server version.