MCP Swagger Server

A Model Context Protocol (MCP) server that converts Swagger/OpenAPI specifications into MCP tools. This project can be used both as a standalone CLI tool and as a Go library for integration into other projects.

Status: ✅ Production Ready - The project is stable, well-tested, and ready for production use.

📖 Documentation: 中文文档 | English Documentation

Features

• Dual Usage: Works as standalone CLI and Go library
• Multiple Transport: Supports stdio and HTTP transport with CORS support
• Complete Swagger Support: Loads Swagger 2.0 and OpenAPI specifications (JSON or YAML)
• Auto-conversion: Automatically converts API endpoints to MCP tools with proper schema generation
• Advanced API Filtering: Comprehensive filtering system to control which APIs become tools
  • Path-based filtering with wildcard support
  • HTTP method filtering (GET, POST, PUT, DELETE, PATCH)
  • Operation ID filtering
  • Tag-based filtering
  • Include-only (whitelist) mode
• Full HTTP Support: Supports all HTTP methods (GET, POST, PUT, DELETE, PATCH)
• Parameter Handling: Intelligent handling of path parameters, query parameters, and request bodies
• Authentication: Automatic API key authentication support with multiple header formats
• Web Integration: Easy integration into existing Go web applications
• HTTP API Endpoints: Built-in HTTP endpoints for tools listing and health checks
• Error Handling: Comprehensive error handling with proper HTTP status codes
• JSON Formatting: Automatic JSON response formatting and validation
• Server Configuration: Flexible configuration system with fluent API

Installation

Using go install (Recommended)

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

This will install the mcp-swagger-server binary in your $GOPATH/bin directory.

Using go get

go get github.com/liliang-cn/mcp-swagger-server

Building from source

git clone https://github.com/liliang-cn/mcp-swagger-server.git
cd mcp-swagger-server
go build -o mcp-swagger-server .

Build

go build -o mcp-swagger-server .

Usage

Standalone CLI Usage

From a local Swagger file:

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

From a URL:

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

With custom API base URL:

./mcp-swagger-server -swagger examples/api.yaml -api-base https://api.example.com

With API key authentication:

./mcp-swagger-server -swagger examples/api.json -api-key YOUR_API_KEY

With HTTP transport:

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

With API filtering (exclude admin endpoints):

./mcp-swagger-server -swagger examples/api.json -exclude-paths "/admin/*,/internal/*"

With multiple filtering options:

./mcp-swagger-server -swagger examples/api.json \
  -exclude-methods "DELETE,PATCH" \
  -exclude-tags "admin,internal" \
  -exclude-paths "/debug/*"

With HTTP transport and filtering:

./mcp-swagger-server -swagger examples/api.json \
  -http-port 8127 \
  -exclude-methods "DELETE,PATCH" \
  -exclude-paths "/admin/*"

Go Library Usage

Basic Library Usage

package main

import (
    "context"
    "log"
    "github.com/liliang-cn/mcp-swagger-server/mcp"
)

func main() {
    // Create MCP server from local file
    server, err := mcp.NewFromSwaggerFile("api.json", "https://api.example.com", "your-api-key")
    if err != nil {
        log.Fatal(err)
    }

    // Run with stdio transport (for CLI usage)
    ctx := context.Background()
    server.RunStdio(ctx)
}

Web Application Integration

package main

import (
    "context"
    "net/http"
    "github.com/liliang-cn/mcp-swagger-server/mcp"
)

func main() {
    // Your existing web app setup
    router := http.NewServeMux()
    
    // Create MCP server from your API swagger
    mcpServer, _ := mcp.NewFromSwaggerFile("your-api.json", "http://localhost:6724", "")

    // Option 1: Run MCP server on separate HTTP port
    go mcpServer.RunHTTP(context.Background(), 8127)
    
    // Option 2: Integrate into existing server (custom implementation needed)
    
    // Your existing routes
    router.HandleFunc("/api/users", handleUsers)

    http.ListenAndServe(":6724", router)
}

Advanced Configuration

config := mcp.DefaultConfig().
    WithAPIConfig("https://api.example.com", "your-api-key").
    WithServerInfo("my-api-server", "v1.0.0", "Custom API MCP Server").
    WithHTTPTransport(8127, "localhost", "/mcp")

server, err := mcp.New(config)
if err != nil {
    log.Fatal(err)
}

// Run with HTTP transport
server.Run(context.Background())

API Filtering in Go Library

// Example 1: Exclude specific paths and methods
config := mcp.DefaultConfig().
    WithSwaggerData(swaggerData).
    WithAPIConfig("https://api.example.com", "your-api-key").
    WithExcludePaths("/admin/*", "/internal/*").
    WithExcludeMethods("DELETE", "PATCH")

server, err := mcp.New(config)
if err != nil {
    log.Fatal(err)
}

// Example 2: Include only specific endpoints
config := mcp.DefaultConfig().
    WithSwaggerData(swaggerData).
    WithAPIConfig("https://api.example.com", "your-api-key").
    WithIncludeOnlyPaths("/users", "/users/{id}", "/posts")

server, err := mcp.New(config)

// Example 3: Complex filtering with custom filter
filter := &mcp.APIFilter{
    ExcludePathPatterns: []string{"/admin/*", "/debug/*"},
    ExcludeMethods:      []string{"DELETE", "PATCH"},
    ExcludeTags:         []string{"internal", "admin"},
    IncludeOnlyOperationIDs: []string{"getUsers", "createUser", "getUser"},
}

config := mcp.DefaultConfig().
    WithSwaggerData(swaggerData).
    WithAPIConfig("https://api.example.com", "your-api-key").
    WithAPIFilter(filter)

server, err := mcp.New(config)

Command Line Options

Basic Options

• -swagger - Path to local Swagger/OpenAPI spec file (JSON or YAML)
• -swagger-url - URL to fetch Swagger/OpenAPI spec from
• -api-base - Override the base URL for API calls (defaults to spec's host)
• -api-key - API key for authentication

Transport Options

• -http-port - HTTP server port (default: 0 = use stdio transport)
• -http-host - HTTP server host (default: localhost)
• -http-path - HTTP server path for MCP endpoint (default: /mcp)

API Filtering Options

• -exclude-paths - Comma-separated list of paths to exclude (supports wildcards like /admin/*)
• -exclude-operations - Comma-separated list of operation IDs to exclude
• -exclude-methods - Comma-separated list of HTTP methods to exclude (e.g., DELETE,PATCH)
• -exclude-tags - Comma-separated list of Swagger tags to exclude
• -include-only-paths - Comma-separated list of paths to include exclusively (whitelist mode)
• -include-only-operations - Comma-separated list of operation IDs to include exclusively

HTTP API Endpoints

When running with HTTP transport, the server exposes the following endpoints:

• GET /health - Health check endpoint with status information
• GET /tools - List available tools with detailed information
• POST /mcp - Execute MCP requests (supports tools/list and tools/call)
• OPTIONS /mcp - CORS preflight support

All HTTP endpoints include CORS headers for cross-origin requests.

Example HTTP Usage

# Get available tools
curl http://localhost:8127/tools

# Execute a tool
curl -X POST http://localhost:8127/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "get_users",
      "arguments": {
        "limit": 10
      }
    }
  }'

Examples

Example Swagger Spec

The examples/petstore.json file contains a sample Swagger specification for testing.

API Filtering Example

Run the API filtering example to see how different filtering options work:

go run examples/api_filtering/main.go

This example demonstrates:

• Path-based exclusion
• HTTP method filtering
• Include-only (whitelist) mode
• Wildcard pattern matching
• Complex filtering combinations
• Direct filter testing

API Filtering

The MCP Swagger Server supports comprehensive API filtering to control which endpoints are exposed as MCP tools. This is essential for security and to prevent unwanted API access.

Filtering Methods

1. Path-based Filtering

# Exclude specific paths
-exclude-paths "/admin,/internal,/debug"

# Exclude paths with wildcards
-exclude-paths "/admin/*,/internal/*,/v1/debug/*"

# Include only specific paths (whitelist mode)
-include-only-paths "/users,/users/{id},/posts"

2. HTTP Method Filtering

# Exclude dangerous methods
-exclude-methods "DELETE,PATCH"

# Only allow read operations
-include-only-methods "GET"

3. Operation ID Filtering

# Exclude specific operations
-exclude-operations "deleteUser,deleteAllData,resetSystem"

# Include only specific operations
-include-only-operations "getUsers,getUser,createUser"

4. Tag-based Filtering

# Exclude operations with specific tags
-exclude-tags "admin,internal,debug"

Filtering Priority

1. Include-only filters are applied first (if specified)
2. Exclude filters are applied second
3. If both include-only and exclude filters