Generic OpenAPI / Swagger MCP Server & Code Generator

Turn any OpenAPI (v3.0 / v3.1) or Swagger (v2.0) specification file (JSON or YAML) into a fully functional Model Context Protocol (MCP) server.

This project supports two operating modes:

1. Dynamic Runtime Mode (main.py): Drop your swagger.json or openapi.yaml into the root directory, configure .env, and immediately serve all API endpoints as LLM tools via MCP.

2. Code Generator Mode (generator.py): Run a simple command to parse any OpenAPI spec and generate standalone, static, readable Python code containing explicit MCP tools with complete docstrings.

🚀 Features

• Universal Support: Parses OpenAPI 2.0 (Swagger) and OpenAPI 3.0 / 3.1 specs in JSON or YAML.

• Reference Resolution: Resolves $ref schema pointer references (#/definitions/... or #/components/schemas/...).

• Rich LLM Docstrings: Formats endpoint summaries, descriptions, path/query/header parameters, and JSON request body structures into clean Markdown for LLMs.

• Flexible Authentication:

  • Bearer Token / JWT

  • API Keys (Custom Header or Query Parameter)

  • Basic Authentication

  • Custom JSON Headers

• Dual Operating Modes: Dynamic execution vs. standalone code generation.

Related MCP server: mcpify

📦 Setup & Installation

1. Prerequisites

• Python >= 3.11

• uv (recommended) or standard pip

2. Install Dependencies

pip install -e .

or with uv:

uv sync

⚙️ Configuration (.env)

Copy .env.example to .env:

cp .env.example .env

🎯 Mode 1: Dynamic Runtime MCP Server (main.py)

Simply place your spec file (e.g., swagger.json) in the project directory and launch:

python main.py

main.py will:

1. Load and dereference swagger.json or openapi.yaml.

2. Discover all paths and HTTP operations.

3. Automatically register each endpoint as an MCP tool with full descriptions.

4. Listen on stdio for MCP client connections (Claude Desktop, Cursor, Smithery, etc.).

🛠️ Mode 2: Standalone Code Generator (generator.py)

Generate a clean, standalone Python script from any spec file:

python generator.py --spec swagger.json --output my_api_mcp.py --name "my-api-service"

Options:

• --spec, -s: Path to spec file (swagger.json, openapi.yaml). Default: swagger.json.

• --output, -o: Output Python file path. Default: generated_mcp.py.

• --name, -n: FastMCP server name identifier. Default: openapi-mcp.

Once generated, run your generated server directly:

python my_api_mcp.py

💻 Integration with Claude Desktop / Cursor / Inspector

Add the server to your MCP client configuration (e.g., claude_desktop_config.json):

{
  "mcpServers": {
    "my-openapi-service": {
      "command": "python",
      "args": [
        "c:/path/to/reward-rally-mcp/main.py"
      ],
      "env": {
        "SWAGGER_PATH": "c:/path/to/your/swagger.json",
        "BASE_URL": "https://api.yourdomain.com",
        "BEARER_TOKEN": "your_api_token_here"
      }
    }
  }
}

🔬 Testing

Run syntax compilation checks:

python -m py_compile main.py generator.py spec_parser.py