mcp-swagger

The MCP Swagger Server is a Go-based MCP server that reads Swagger/OpenAPI specifications and automatically generates MCP tools from them. It can operate as a standalone CLI tool or be used as a Go library within other applications. When run, the server loads a Swagger/OpenAPI spec (JSON or YAML), applies filtering and authentication rules, and exposes MCP tools derived from the API definitions. It also provides HTTP transport support (with CORS) so you can interact with the server over HTTP in addition to the standard stdio transport for CLI usage. Typical usage involves either running the CLI to generate or test tools from a local spec or embedding the library into a web app or service to dynamically expose MCP capabilities based on your API definitions.

Key capabilities include:

• Loading Swagger 2.0 and OpenAPI specifications (JSON or YAML) and converting endpoints to MCP tools with correct schema
• Flexible API filtering (by path, method, operation ID, tags) and include/whitelist modes
• Automatic authentication handling for API calls (API keys via headers)
• Both stdio and HTTP transports with CORS support for integration into web services
• Built-in HTTP endpoints for tooling discovery, health checks, and executing MCP requests
• Convenient Go library usage for embedding in existing Go projects

To use the CLI, provide a Swagger/OpenAPI spec via a local file or URL, and optionally enable HTTP transport or filtering. As a library, create and configure the MCP server in code, then run it in your application context or expose it via an HTTP server.

Prerequisites:

• Go 1.24 or newer installed on your system
• Git (for cloning the repository or fetching dependencies)
• A compatible environment where you plan to run the MCP Swagger Server (CLI or library usage)

Install via Go install (recommended):

go install github.com/liliang-cn/mcp-swagger-server@latest

This will place the mcp-swagger-server binary in your $GOPATH/bin directory, and you can run it directly as a CLI tool.

Alternative: fetch and build from source

git clone https://github.com/liliang-cn/mcp-swagger-server.git
cd mcp-swagger-server
# Build the CLI binary (example output: mcp-swagger-server)
go build -o mcp-swagger-server .

Usage examples (CLI):

• Run with a local Swagger file

./mcp-swagger-server -swagger examples/petstore.json

• Run with a Swagger URL

./mcp-swagger-server -swagger-url https://petstore.swagger.io/v2/swagger.json

• Run with HTTP transport

./mcp-swagger-server -swagger examples/api.json -http-port 8127

If you prefer, you can also integrate the library directly into your Go project as shown in the examples in the README.

Tips and common considerations:

• This MCP server can operate as both a standalone CLI and as a Go library; choose the mode that fits your workflow.
• When using HTTP transport, the server exposes health at GET /health and tooling at GET /tools, with MCP execution available at POST /mcp. CORS is enabled for cross-origin requests.
• Filtering options are important to control which endpoints become MCP tools. You can exclude paths, methods, operation IDs, or tags, or use include-only (whitelist) mode.
• For authentication, the server supports API key authentication and can handle multiple header formats. Ensure your API keys are provided via the -api-key flag (CLI) or via the configuration in code.
• If using the library, you can run the server in a separate goroutine or integrate it into an existing HTTP server, enabling more complex deployment architectures.
• Build and run locally to verify compatibility with your Swagger/OpenAPI spec before deploying to production.
• If you encounter issues with Go module resolution, ensure GOPROXY is set appropriately and that your network access to the module proxy is available.