zecure/mcp_swagger

MCP Swagger Server

Generate MCP (Model Context Protocol) servers from Swagger/OpenAPI specifications with flexible filtering.

Features

• Dynamic Tool Generation: Automatically creates MCP tools from OpenAPI endpoints
• Flexible Filtering: Control exposed endpoints via HTTP methods, paths, tags, and operation IDs
• Authentication: Built-in Bearer token support
• Type Safety: Automatic parameter validation and conversion
• FastMCP Integration: Built on the FastMCP framework for reliable MCP server implementation

Installation

# Install from source
pip install -e .

# Or install dependencies directly
pip install -r requirements.txt

Quick Start

# Basic usage (exposes GET endpoints by default)
mcp-swagger path/to/swagger.json

# With authentication
mcp-swagger swagger.json --api-token "your-token"

# Custom base URL
mcp-swagger swagger.json --base-url "https://api.example.com"

Filtering Options

Control which endpoints are exposed:

• HTTP Methods: --methods get post put delete
• Path Patterns: --paths "/api/*" --exclude-paths "/admin/*"
• Tags: --tags public documents --exclude-tags internal
• Operation IDs: --operation-ids list_docs get_doc --exclude-operation-ids delete_all

Examples

# Public read-only API
mcp-swagger api.json --methods get --tags public --exclude-paths "/admin/*"

# Specific operations only
mcp-swagger api.json --operation-ids list_docs get_doc search_docs

# Preview generated tools without starting server
mcp-swagger api.json --dry-run --methods get post

Configuration

Command Line Options

• --host: Server host (default: localhost)
• --port: Server port (default: 8080)
• --transport: Transport protocol: sse or streamable-http (default)
• --timeout: Request timeout in seconds (default: 30)
• --dry-run: Preview tools without starting server

Environment Variables

• API_BASE_URL: Default base URL for the API
• API_TOKEN: API token for authentication

Docker

# Build image
docker build -t mcp-swagger .

# Run with configuration
docker run -p 8080:8080 \
  -e API_BASE_URL=https://api.example.com \
  -e API_TOKEN=your-token \
  -v $(pwd)/swagger.json:/app/swagger.json \
  mcp-swagger /app/swagger.json --methods get post

Architecture

• config/: CLI parsing and settings
• filters/: Endpoint filtering logic
• generators/: MCP tool generation
• parsers/: OpenAPI spec parsing
• api_client/: HTTP client and auth
• models/: Data models
• utils/: Utilities and logging

How It Works

1. Load OpenAPI/Swagger specification (file or URL)
2. Apply filters to select endpoints
3. Generate FastMCP tools with parameter validation and auth
4. Start MCP server with generated tools