🚀 OpenAPI to FastMCP 3.x Server Generator

Transform any OpenAPI specification into a production-ready Model Context Protocol (MCP) server with enterprise-grade authentication, modular architecture, and comprehensive middleware support.

MCP Generator 3.1 is an advanced code generator that automatically creates FastMCP 3.x servers from OpenAPI 3.0.x/3.1.x specifications. It bridges REST APIs and AI agents by generating fully-functional MCP tools that AI assistants like Claude, ChatGPT, and others can use to interact with your APIs.

• ✅ OpenAPI 3.0.x - Fully supported (recommended)
• ✅ OpenAPI 3.1.x - Fully supported
• ✅ Swagger 2.0 - Fully supported

Note: Both JSON and YAML formats are supported. The generator includes a pure Python OpenAPI client generator — no Java or Node.js required.

How MCP Generator 3.1 stacks up against every other OpenAPI-to-MCP project on GitHub:

Note: mcpo (4,027★) solves the inverse problem — exposing MCP servers as OpenAPI endpoints — and is complementary rather than competitive.

MCP Generator 3.1 leverages all the latest FastMCP 3.0/3.1 capabilities:

All features are configurable via the generated fastmcp.json:

{
  "features": {
    "search_tools": { "enabled": false },
    "code_mode": { "enabled": false },
    "response_limiting": { "enabled": true, "max_size_bytes": 1048576 },
    "ping_middleware": { "enabled": true },
    "opentelemetry": { "enabled": false, "service_name": "my-api-mcp" }
  }
}

• Python 3.11+: Required for modern type hints and features
• uv (recommended) or pip: For dependency management
• OpenAPI Specification: Your API's OpenAPI 3.0.x or 3.1.x spec file (JSON or YAML)

# Clone the repository
git clone https://github.com/quotentiroler/mcp-generator-2.0.git
cd mcp-generator-2.0

# Install dependencies
uv sync

# Verify installation
uv run generate-mcp --help

# Clone the repository
git clone https://github.com/quotentiroler/mcp-generator-2.0.git
cd mcp-generator-2.0

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e .

# Verify installation
generate-mcp --help

# Using local file (default: ./openapi.json)
uv run generate-mcp

# Using custom file
uv run generate-mcp --file ./my-api-spec.yaml

# Download from URL
uv run generate-mcp --url https://petstore3.swagger.io/api/v3/openapi.json

What happens:

• ✅ Generates Python API client from OpenAPI spec
• ✅ Auto-discovers undeclared tags from API paths (tag auto-discovery)
• ✅ Creates modular MCP server modules
• ✅ Generates authentication middleware
• ✅ Creates OAuth2 provider
• ✅ Writes package files and tests
• ✅ Outputs to generated_mcp/ directory

By default, the generator creates a minimal, production-ready server. Enable additional features as needed:

# Enable persistent storage (for OAuth tokens, session state)
uv run generate-mcp --enable-storage

# Enable response caching (reduces backend API calls)
uv run generate-mcp --enable-storage --enable-caching

# Enable MCP resources (expose API data as resources)
uv run generate-mcp --enable-resources

# Enable all features
uv run generate-mcp --enable-storage --enable-caching --enable-resources

Available Features:

Note: --enable-caching requires --enable-storage as it uses the storage backend for cache persistence.

Why disabled by default?

• Keeps generated code simple and focused
• Fewer dependencies to manage
• Easier to understand and customize
• Most APIs work perfectly without these features

The generator will show which features are available at the end of generation with a copy-paste command to re-generate with features enabled.

💡 Tip: Run uv run generate-mcp --help to see all available options and examples.

# Register the generated server
uv run register-mcp ./generated_mcp

# Verify registration
uv run run-mcp --list

This adds your server to the local registry at ~/.mcp-generator/servers.json so you can easily run it by name.

# Option 1: Run via registry (STDIO mode for local AI clients)
export BACKEND_API_TOKEN="your-api-token-here"  # On Windows: set BACKEND_API_TOKEN=...
uv run run-mcp swagger_petstore_openapi

# Option 2: Run via registry (HTTP mode)
uv run run-mcp swagger_petstore_openapi --mode http --port 8000

# Option 3: Run directly with Python
cd generated_mcp
python swagger_petstore_openapi_mcp_generated.py --transport stdio

# Option 4: Run with FastMCP CLI
cd generated_mcp
# Note: Use :create_server to properly compose the server
uv run fastmcp run swagger_petstore_openapi_mcp_generated.py:create_server
# Or with fastmcp.json config:
uv run fastmcp run fastmcp.json

Add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "my-api": {
      "command": "python",
      "args": ["/path/to/generated_mcp/swagger_petstore_openapi_mcp_generated.py"],
      "env": {
        "BACKEND_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

The MCP Inspector is the official debugging tool for MCP servers. It provides both a visual UI and CLI mode for testing your generated servers.

# Generate your MCP server first
uv run generate-mcp --file ./openapi.json

# Test with Inspector using FastMCP (recommended)
cd generated_mcp
uv run fastmcp dev swagger_petstore_openapi_mcp_generated.py:create_server

# Or test directly with Python
npx @modelcontextprotocol/inspector python swagger_petstore_openapi_mcp_generated.py

# Or use environment variables
npx @modelcontextprotocol/inspector -e BACKEND_API_TOKEN=your-token python swagger_petstore_openapi_mcp_generated.py

Note: When using fastmcp dev or fastmcp run, always include :create_server to properly compose the modular server architecture.

The Inspector will:

• 🚀 Start your MCP server
• 🌐 Open a browser UI at http://localhost:6274
• 🔗 Connect via proxy at http://localhost:6277
• 🔑 Generate a secure session token

🛠️ Tool Testing

• List all available tools generated from your OpenAPI spec
• Interactive form-based parameter input
• Real-time response visualization with JSON formatting
• Test OAuth2 authentication flows

📦 Resource Exploration

• Browse API resources hierarchically
• View resource metadata and content
• Test resource subscriptions

💬 Prompt Testing

• Interactive prompt sampling
• Streaming response visualization
• Compare multiple prompt variations

📊 Debugging

• Request/response history
• Visualized error messages
• Real-time server notifications
• Network timing information

Perfect for CI/CD and rapid development cycles:

# List available tools
npx @modelcontextprotocol/inspector --cli python swagger_petstore_openapi_mcp_generated.py --method tools/list

# Call a specific tool
npx @modelcontextprotocol/inspector --cli python swagger_petstore_openapi_mcp_generated.py \
  --method tools/call \
  --tool-name create_pet \
  --tool-arg 'name=Fluffy' \
  --tool-arg 'status=available'

# Test with environment variables
npx @modelcontextprotocol/inspector --cli \
  -e BACKEND_API_TOKEN=your-token \
  python swagger_petstore_openapi_mcp_generated.py \
  --method tools/list

If your generated server runs in HTTP mode:

# Start your server in HTTP mode
cd generated_mcp
python swagger_petstore_openapi_mcp_generated.py --transport http --port 8000

# Connect Inspector to running server (SSE transport)
npx @modelcontextprotocol/inspector http://localhost:8000/sse

# Or use Streamable HTTP transport
npx @modelcontextprotocol/inspector http://localhost:8000/mcp --transport http

The Inspector can export your server configuration for use in Claude Desktop or other MCP clients:

1. Server Entry Button - Copies a single server config to clipboard
2. Servers File Button - Copies complete mcp.json structure

Example exported config:

{
  "mcpServers": {
    "my-api": {
      "command": "python",
      "args": ["swagger_petstore_openapi_mcp_generated.py"],
      "env": {
        "BACKEND_API_TOKEN": "your-token"
      }
    }
  }
}

Integrate Inspector into your development cycle:

# 1. Generate server from OpenAPI spec
uv run generate-mcp --file ./openapi.yaml

# 2. Test with Inspector UI (interactive development)
cd generated_mcp
npx @modelcontextprotocol/inspector -e BACKEND_API_TOKEN=test python *_mcp_generated.py

# 3. Automated testing (CI/CD)
npx @modelcontextprotocol/inspector --cli \
  -e BACKEND_API_TOKEN=test \
  python *_mcp_generated.py \
  --method tools/list > tools.json

# 4. Test specific tools
npx @modelcontextprotocol/inspector --cli \
  -e BACKEND_API_TOKEN=test \
  python *_mcp_generated.py \
  --method tools/call \
  --tool-name get_user \
  --tool-arg 'user_id=123'

• JWT Validation: Use Inspector to test JWT authentication flows with --validate-tokens
• OAuth2 Flows: Inspector supports bearer token auth for testing OAuth2
• Scope Testing: Verify scope enforcement in your OAuth2 configuration
• Error Handling: Inspector visualizes error responses and stack traces
• Performance: Use Inspector's timing metrics to identify slow operations

For more details, see the Inspector documentation.

This project installs three CLI commands. Here's a quick cheatsheet.

• Description: Generate a FastMCP 3.x server from an OpenAPI 3.0.x/3.1.x spec.
• Options:
  • --file Path to spec file (default: ./openapi.json)
  • --url Download spec from URL (overrides --file)
• Examples:

# Use local file (default)
uv run generate-mcp

# Custom file
uv run generate-mcp --file ./my-api.yaml

# From URL
uv run generate-mcp --url https://petstore3.swagger.io/api/v3/openapi.json

• Description: Manage the local registry at ~/.mcp-generator/servers.json
• Subcommands:
  • add Register a generated server (default when passing a path)
  • list Show all registered servers
    • --json Output as JSON for scripting/automation
  • remove Unregister a server by name
  • export Export server metadata as server.json for MCP Registry publishing
    • -o, --output Write to file (default: stdout)
• Examples:

# Add (explicit)
uv run register-mcp add ./generated_mcp

# Add (implicit)
uv run register-mcp ./generated_mcp

# List registered servers
uv run register-mcp list

# List as JSON
uv run register-mcp list --json

# Remove by name
uv run register-mcp remove swagger_petstore_openapi

# Export server metadata for publishing
uv run register-mcp export swagger_petstore_openapi -o server.json

• Description: Run a registered server by name.
• Flags:
  • --list List registered servers and exit
  • --mode/--transport stdio | http (default: stdio)
  • --host HTTP host (default: 0.0.0.0)
  • --port HTTP port (default: 8000)
  • --validate-tokens Enable JWT validation (HTTP mode)
• Examples:

# List servers
uv run run-mcp --list

# Run via STDIO (Linux/macOS)
export BACKEND_API_TOKEN="your-api-token" && uv run run-mcp swagger_petstore_openapi

# Run via STDIO (Windows PowerShell)
powershell
$env:BACKEND_API_TOKEN = "your-api-token"
uv run run-mcp swagger_petstore_openapi

# Run via HTTP
uv run run-mcp swagger_petstore_openapi --mode http --port 8000

# HTTP with JWT validation
uv run run-mcp swagger_petstore_openapi --mode http --port 8000 --validate-tokens

Notes:

• The registry file lives at ~/.mcp-generator/servers.json
• run-mcp forwards these flags to the generated server’s entry point.
• You can also run the generated script directly: python _mcp_generated.py

Use register-mcp to quickly create a local internal registry of MCP servers you generate. Entries live in ~/.mcp-generator/servers.json; add/list/remove in seconds, and run-mcp lets you start servers by name. You can run multiple servers side‑by‑side (e.g., different HTTP ports) for a smooth developer workflow.

You can run your own MCP Registry (open source) and publish your generated servers to it:

• Deploy the official Registry service on your infra (Docker Compose/Kubernetes). Configure TLS, database (PostgreSQL), and a public base URL.
• Configure authentication/ownership verification: either set up GitHub OAuth/OIDC in the Registry, or use DNS/HTTP challenges to prove domain ownership for your namespace.
• Make your MCP server reachable over HTTP and provide valid server metadata (server.json) per the Registry schema.
• Use the publisher CLI to point at your Registry’s base URL, authenticate, and publish your server. After validation, it becomes discoverable via your Registry’s API/UI.

Note: This project does not (yet) auto-publish. The local per-user registry (~/.mcp-generator/servers.json) is for development convenience; publishing to a central catalog is an optional, separate step.

Automatically generates OAuth2 provider when OpenAPI spec contains OAuth2 security schemes.

Supported Flows:

• Implicit flow
• Authorization code flow
• Client credentials flow
• Password flow

Features:

• Scope extraction and validation
• Token introspection
• JWKS-based JWT verification
• Scope enforcement middleware

When --validate-tokens is enabled:

1. Token Extraction: Extracts JWT from Authorization header
2. JWKS Discovery: Auto-discovers JWKS endpoint from OpenAPI spec or uses standard well-known path
3. Signature Verification: Validates JWT signature using public key
4. Claims Validation: Checks expiration, issuer, audience
5. Scope Enforcement: Verifies required scopes for operations
6. Identity Injection: Makes user identity available to tools

Configuration:

The JWKS URI, issuer, and audience are automatically extracted from your OpenAPI specification's security schemes during generation. If not specified in the OpenAPI spec, sensible defaults are used:

• JWKS URI: {backend_url}/.well-known/jwks.json
• Issuer: {backend_url}
• Audience: backend-api

Simply enable JWT validation when running:

python server_generated.py --transport http --validate-tokens

Or set as default in fastmcp.json:

{
  "middleware": {
    "config": {
      "authentication": {
        "validate_tokens": true
      }
    }
  }
}

Note: All JWT configuration is baked into the generated code - no environment variables needed!

Edit mcp_generator/config.py:

# Abbreviations for long names
TOOL_NAME_ABBREVIATIONS = {
    'healthcare': 'hc',
    'organization': 'org',
}

# Complete overrides
TOOL_NAME_OVERRIDES = {
    'list_healthcare_users_by_role': 'list_users_by_role',
    'create_smart_app_registration': 'register_smart_app',
}

# Maximum tool name length (MCP/OpenAI limit)
MAX_TOOL_NAME_LENGTH = 64

# Format code
uv run ruff format .

# Lint code
uv run ruff check .

# Type checking
uv run mypy mcp_generator/

# Generate MCP server from example
uv run generate-mcp --file openapi.yaml

# Validate OpenAPI spec
uv run python scripts/validate_openapi.py

# Generate JWT keypair for testing
uv run python scripts/generate_jwt_keypair.py

# Generate from Petstore API
uv run generate-mcp --url https://petstore3.swagger.io/api/v3/openapi.json

# Run the server
cd generated_mcp
python swagger_petstore_openapi_mcp_generated.py

# Download GitHub OpenAPI spec
uv run generate-mcp --url https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json

# Outputs: 300+ tools for GitHub API operations

Contributions are welcome! Here's how to contribute:

1. Check existing issues: https://github.com/quotentiroler/mcp-generator-2.0/issues
2. Create detailed bug report with:
   • OpenAPI spec (sanitized/minimal example)
   • Full error message and stack trace
   • Steps to reproduce
   • Expected vs actual behavior

1. Open a feature request issue
2. Describe the use case and benefit
3. Provide examples if applicable

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Run tests: uv run pytest
5. Format code: uv run ruff format .
6. Commit: git commit -m 'Add amazing feature'
7. Push: git push origin feature/amazing-feature
8. Open a Pull Request

• Follow existing code style (Ruff formatting)
• Add tests for new features
• Update documentation as needed
• Keep commits focused and descriptive

This project is licensed under the Apache License 2.0.

✅ You can:

• Use this software for any purpose (commercial or non-commercial)
• Modify the source code
• Distribute the software
• Include it in proprietary software
• Use it in SaaS applications
• Patent protection is granted

⚠️ You must:

• Include the original license and copyright notice
• State significant changes made to the code
• Include a copy of the Apache 2.0 license in your distribution

❌ You cannot:

• Use the project's trademarks without permission
• Hold the authors liable

Apache 2.0 is a permissive license that promotes wide adoption while providing patent protection. It's business-friendly, widely accepted by enterprises, and commonly used for development tools and code generators. This license allows you to use MCP Generator 3.1 in your projects without worrying about copyleft requirements.

Generated Code: The code generated by this tool is NOT considered a derivative work of the generator itself. You may license your generated MCP servers however you choose.

For the full license text, see LICENSE or visit https://www.apache.org/licenses/LICENSE-2.0

• FastMCP: Built on the excellent FastMCP 3.x framework
• OpenAPI Generator: Uses OpenAPI Generator for client generation
• Model Context Protocol: Implements the MCP specification
• Anthropic: For the MCP standard and Claude Desktop integration

If you find this project useful, please consider giving it a star! ⭐

It helps others discover the tool and motivates continued development.