MCP Swagger CLI

MCP Swagger CLI is a command-line tool that generates runnable MCP servers from Swagger/OpenAPI specifications. It maps API operations to MCP Tools, schemas to MCP Resources, and provides a complete, ready-to-use MCP server implementation.

Features

• Parse OpenAPI 3.x and Swagger 2.0 specifications
• Generate MCP Tools from API operations (GET, POST, PUT, DELETE, etc.)
• Generate MCP Resources from API schemas
• Multiple transport support: stdio and SSE/HTTP
• Automatic type conversion from JSON Schema to Python types
• CLI with progress feedback and validation

Installation

Using pip

pip install mcp-swagger-cli

Using uv (recommended for speed)

uv pip install mcp-swagger-cli

Development Installation

git clone https://github.com/mcp-swagger/mcp-swagger-cli.git
cd mcp-swagger-cli
pip install -e .

Usage

Basic Usage

Generate an MCP server from a Swagger/OpenAPI specification:

mcp-swagger create https://petstore.swagger.io/v2/swagger.json -o ./my_mcp_server

With Custom Options

mcp-swagger create ./api_spec.yaml \
    --output ./my_server \
    --name my_api \
    --transport stdio \
    --base-url https://api.example.com \
    --api-key-env MY_API_KEY \
    --api-key-header Authorization \
    --api-key-prefix Bearer

Validate a Specification

Before generating, validate your OpenAPI spec:

mcp-swagger validate-spec https://petstore.swagger.io/v2/swagger.json

View Spec Information

Display information about a specification without generating:

mcp-swagger info https://petstore.swagger.io/v2/swagger.json

Command Reference

mcp-swagger create

Create an MCP server from a Swagger/OpenAPI specification.

Usage: mcp-swagger create <spec> [OPTIONS]

Arguments:
  spec                  URL or file path to Swagger/OpenAPI specification

Options:
  -o, --output PATH           Output directory for generated MCP server
  -n, --name TEXT             Name for the generated MCP server
  -t, --transport TEXT        Transport type (stdio or sse)
  -b, --base-url TEXT         Base URL for API requests
  --validate / --no-validate  Validate specification before generating
  -f, --force                 Overwrite output directory if it exists
  -v, --verbose               Enable verbose output
  --api-key-env TEXT          Environment variable name to read API key from at runtime
  --api-key-header TEXT       HTTP header name for API key (default: Authorization)
  --api-key-prefix TEXT       Prefix for API key in header (e.g., 'Bearer', 'Token', 'Bot', or empty)
  -H, --header TEXT           Custom HTTP header as 'Name: Value' (repeatable)
  -T, --tag TEXT              Filter operations by tag (repeatable)
  --path-filter TEXT          Filter operations by path substring (repeatable)
  --max-operations INT        Warn and abort if filtered operation count exceeds this number
  --help                      Show this message and exit.

Filtering Large Specs

Large APIs like Stripe or Discord can generate unmanageably large servers. Use --path-filter or --tag to scope generation:

# Filter by path substring (Discord guild endpoints only)
mcp-swagger create ./discord.json -o ./server --path-filter /guilds --path-filter /channels

# Filter by tag
mcp-swagger create ./api.json -o ./server --tag payments --tag customers

# Abort if too many operations
mcp-swagger create ./api.json -o ./server --max-operations 50

Note: Some APIs (e.g. Stripe) use a single default tag for all operations. Use --path-filter instead of --tag for these.

mcp-swagger validate-spec

Validate a Swagger/OpenAPI specification.

Usage: mcp-swagger validate-spec <spec> [OPTIONS]

Arguments:
  spec    URL or file path to Swagger/OpenAPI specification

Options:
  -v, --verbose    Show detailed validation results
  --help           Show this message and exit.

mcp-swagger info

Show information about a Swagger/OpenAPI specification.

Usage: mcp-swagger info <spec> [OPTIONS]

Arguments:
  spec    URL or file path to Swagger/OpenAPI specification

Options:
  --help    Show this message and exit.

Generated Server Usage

After generating an MCP server, follow these steps to use it:

1. Install the Server

cd my_mcp_server
pip install -e .

2. Run the Server

Stdio Transport (recommended for Claude Desktop):

my_mcp_server

SSE Transport (for remote access):

my_mcp_server --sse 8000

3. Configure with Claude Desktop

Add to your Claude Desktop config:

{
  "mcpServers": {
    "my_mcp_server": {
      "command": "my_mcp_server",
      "args": []
    }
  }
}

How It Works

MCP Swagger CLI parses your OpenAPI/Swagger specification and generates:

1. MCP Tools - Each API operation becomes an MCP tool with:

   • Tool name from operationId (or generated)
   • Description from summary/description
   • Parameters from path/query/header parameters
   • Request body support

2. MCP Resources - Each schema becomes an MCP resource:

   • schema://api/schemas - List of all schemas
   • schema://api/{schema_name} - Individual schema definitions
   • api://operations - List of all operations

3. Transport - Supports:

   • stdio - Standard I/O (local, default)
   • sse - Server-Sent Events over HTTP

Examples

See the examples directory for sample specifications and usage.

Development

Running Tests

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

Project Structure

mcp-swagger-cli/
├── mcp_swagger_cli/
│   ├── __init__.py
│   ├── cli.py           # CLI commands
│   ├── generator.py     # Server generation logic
│   ├── parser.py        # OpenAPI parsing
│   ├── exceptions.py    # Custom exceptions
│   └── templates/       # Jinja2 templates
├── tests/               # Test suite
├── pyproject.toml       # Project configuration
└── README.md            # This file

Requirements

• Python 3.10+
• typer (CLI framework)
• httpx (HTTP client)
• prance (OpenAPI parser)
• jinja2 (template engine)

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please read our contributing guidelines first.

Related

• MCP Python SDK - Official MCP Python implementation
• FastMCP - High-level MCP framework
• OpenAPI Specification - OpenAPI standard