liliang-cn/mcp-swagger-server
If you are the rightful owner of mcp-swagger-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
The MCP Swagger Server is a tool that converts Swagger/OpenAPI specifications into Model Context Protocol (MCP) tools, facilitating seamless integration and interaction with APIs.
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.
Features
- Dual Usage: Works as standalone CLI and Go library
- Multiple Transport: Supports stdio and HTTP transport
- Complete Swagger Support: Loads Swagger 2.0 and OpenAPI specifications (JSON or YAML)
- Auto-conversion: Automatically converts API endpoints to MCP tools
- API Filtering: Advanced filtering to control which APIs become tools
- Full HTTP Support: Supports all HTTP methods (GET, POST, PUT, DELETE, PATCH)
- Parameter Handling: Handles path parameters, query parameters, and request bodies
- Authentication: Automatic API key authentication support
- Web Integration: Easy integration into existing Go web applications
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 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/*"
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:6666", "")
// Option 1: Run MCP server on separate HTTP port
go mcpServer.RunHTTP(context.Background(), 7777)
// Option 2: Integrate into existing server (custom implementation needed)
// Your existing routes
router.HandleFunc("/api/users", handleUsers)
http.ListenAndServe(":6666", 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(7777, "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
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 endpointGET /tools
- List available toolsPOST /mcp
- Execute MCP requests
Example HTTP Usage
# Get available tools
curl http://localhost:7777/tools
# Execute a tool
curl -X POST http://localhost:7777/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
- Include-only filters are applied first (if specified)
- Exclude filters are applied second
- If both include-only and exclude filters are specified, an endpoint must pass both
Wildcard Patterns
The filtering system supports wildcard patterns for paths:
*
matches any characters within a path segment/admin/*
matches/admin/users
,/admin/settings
, etc./api/v*/admin
matches/api/v1/admin
,/api/v2/admin
, etc.
Security Best Practices
- Always exclude administrative endpoints: Use
-exclude-paths "/admin/*"
- Limit dangerous HTTP methods: Use
-exclude-methods "DELETE,PATCH"
- Use whitelist mode for sensitive APIs: Use
-include-only-paths
for maximum control - Exclude internal/debug endpoints: Use
-exclude-tags "internal,debug"
Examples
# Security-focused filtering
./mcp-swagger-server -swagger api.json \
-exclude-paths "/admin/*,/internal/*,/debug/*" \
-exclude-methods "DELETE,PATCH" \
-exclude-tags "admin,internal"
# Whitelist mode - only allow user operations
./mcp-swagger-server -swagger api.json \
-include-only-paths "/users,/users/{id}" \
-include-only-operations "getUsers,getUser,createUser"
How It Works
- The server loads a Swagger/OpenAPI specification
- API filtering rules are applied to determine which endpoints to expose
- Each allowed API endpoint is converted to an MCP tool
- Tool names are derived from the operation ID or the path
- Parameters are converted to MCP tool input schemas
- When a tool is called, the server makes the corresponding HTTP request
- Response data is returned to the MCP client
MCP Client Configuration
To use this server with an MCP client, configure it to run:
{
"servers": {
"swagger-api": {
"command": "./mcp-swagger-server",
"args": ["-swagger", "path/to/your/api.json"]
}
}
}
Testing
Run the test suite:
go test ./mcp -v
Run tests with race condition detection:
go test ./mcp -v -race
The project includes comprehensive unit tests covering:
- Configuration management and fluent API
- Swagger specification parsing and validation
- Base URL inference and parameter handling
- Transport layer functionality
- Core library creation and validation logic
- API filtering and exclusion rules
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/AmazingFeature
) - Commit your changes (
git commit -m 'Add some AmazingFeature'
) - Push to the branch (
git push origin feature/AmazingFeature
) - Open a Pull Request
Dependencies
License
This project is licensed under the MIT License - see the file for details.
Author
liliang-cn
Acknowledgments
- Model Context Protocol for the MCP SDK
- OpenAPI Initiative for the OpenAPI Specification