Generator 3.x
Generate FastMCP 3.x Servers from OpenAPI Specs
Ask AI about Generator 3.x
Powered by Claude Β· Grounded in docs
I know everything about Generator 3.x. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
MCP Generator 3.1
π 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.
π― Overview
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.
Supported OpenAPI Versions
- β 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.
π Why MCP Generator 3.1?
| Feature | MCP Generator 3.1 | Typical Generators |
|---|---|---|
| Architecture | Modular, composable sub-servers | Monolithic single file |
| Authentication | JWT validation with JWKS, OAuth2 flows | Basic token passing |
| Middleware System | Full FastMCP 3.x middleware stack | Limited or none |
| Scalability | One module per API class | All operations in one file |
| Type Safety | Full Pydantic model support | Basic validation |
| Testing | Auto-generated test suites | Manual testing only |
| Observability | Timing, logging, error handling middleware | Basic logging |
| Tag Discovery | Auto-discovers undeclared API tags | Manual tag mapping |
| Event Store | Resumable SSE with event persistence | Simple SSE |
| Production Ready | β Yes | β οΈ Often prototypes |
Competitive Comparison
How MCP Generator 3.1 stacks up against every other OpenAPI-to-MCP project on GitHub:
| Feature | MCP Generator 3.1 (Py, 13β ) | openapi-mcp-generator (TS, 531β ) | mcp-link (Go, 602β ) | openapi-mcp-codegen (Py, 33β ) | openapi-mcp-generator (Py, 28β ) |
|---|---|---|---|---|---|
| Approach | Code generation | Code generation | Runtime proxy | Code generation | Code generation |
| OpenAPI 3.0 | β | β | β | β | β |
| OpenAPI 3.1 | β | β | β | β | β |
| Swagger 2.0 | β | β | β | β | β |
| Modular sub-servers | β | β | β | β | β |
| FastMCP 3.x native | β | β | N/A | β | β |
| Streamable HTTP | β | β | β | β | β |
| JWT / JWKS auth | β | β | β | β | β |
| OAuth2 flows | β | env vars only | β | β | β |
| Middleware stack | β (timing, logging, cache, auth) | β | β | β | β |
| MCP Resources | β (GET endpoints) | β | β | β | β |
| Event Store | β (resumable) | β | β | β | β |
| Auto-generated tests | β | β | β | β | β |
| Docker output | β | β | β | β | β |
| Tag auto-discovery | β | β | β | β | β |
| Server registry | β | β | β | β | β |
| Pure Python | β (zero external deps) | β (Node.js) | β (Go binary) | β | β |
| Schema validation | Pydantic | Zod | β | β | β |
Note: mcpo (4,027β ) solves the inverse problem β exposing MCP servers as OpenAPI endpoints β and is complementary rather than competitive.
β¨ FastMCP 3.1 Features
MCP Generator 3.1 leverages all the latest FastMCP 3.0/3.1 capabilities:
| Feature | Description |
|---|---|
| Tool Tags | Automatic per-module tag grouping (@mcp.tool(tags=["pet"])) |
| Tool Timeouts | Configurable per-tool timeout (default 30s) |
| SearchTools | BM25 text search over tool catalog (opt-in via fastmcp.json) |
| CodeMode | Experimental meta-tool transform (opt-in via fastmcp.json) |
| ResponseLimitingMiddleware | UTF-8-safe truncation of oversized responses (1MB default) |
| PingMiddleware | HTTP keepalive for long-lived connections |
| MultiAuth | Compose multiple token verifiers (JWT + OAuth2, etc.) |
| Component Versioning | Deprecated OpenAPI endpoints annotated automatically |
| Dynamic Visibility | Per-session component toggling via scopes |
| OpenTelemetry | Tracing with MCP semantic conventions (Console/OTLP export) |
| validate_output | FastMCP output validation support |
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" }
}
}
π¦ Installation
Prerequisites
- 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)
Install with uv (Recommended)
# 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
Install with pip
# 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
π Quick Start
1. Generate MCP Server from OpenAPI Spec
# 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
Optional Features (Disabled by Default)
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:
| Flag | Description | When to Use |
|---|---|---|
--enable-storage | Persistent storage backend | OAuth refresh tokens, session data, user preferences |
--enable-caching | Response caching with TTL | Rate-limited APIs, expensive operations, slow endpoints |
--enable-resources | MCP resource templates | Expose API data for context/retrieval (GET endpoints) |
Note:
--enable-cachingrequires--enable-storageas 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.
2. Register Your MCP Server
# 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.
3. Run Your MCP Server
# 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
4. Use with AI Clients
Claude Desktop (STDIO Mode)
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"
}
}
}
}
π Testing with MCP Inspector
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.
Quick Start with Inspector
# 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 devorfastmcp run, always include:create_serverto 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
Inspector Features for Your Generated Servers
π οΈ 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
CLI Mode for Automation
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
Testing HTTP/SSE Transports
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
Export Configuration
The Inspector can export your server configuration for use in Claude Desktop or other MCP clients:
- Server Entry Button - Copies a single server config to clipboard
- Servers File Button - Copies complete
mcp.jsonstructure
Example exported config:
{
"mcpServers": {
"my-api": {
"command": "python",
"args": ["swagger_petstore_openapi_mcp_generated.py"],
"env": {
"BACKEND_API_TOKEN": "your-token"
}
}
}
}
Development Workflow
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'
Tips for Testing Generated Servers
- 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.
π§° CLI reference
This project installs three CLI commands. Here's a quick cheatsheet.
generate-mcp
- 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
register-mcp
- 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
run-mcp
- 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
Internal registry (local)
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.
Publish to a self-hosted MCP Registry
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.
OAuth2 Support
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
JWT Validation
When --validate-tokens is enabled:
- Token Extraction: Extracts JWT from
Authorizationheader - JWKS Discovery: Auto-discovers JWKS endpoint from OpenAPI spec or uses standard well-known path
- Signature Verification: Validates JWT signature using public key
- Claims Validation: Checks expiration, issuer, audience
- Scope Enforcement: Verifies required scopes for operations
- 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!
βοΈ Configuration
Tool Name Customization
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
Code Quality
# Format code
uv run ruff format .
# Lint code
uv run ruff check .
# Type checking
uv run mypy mcp_generator/
Project Commands
# 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
π Examples
Example 1: Swagger Petstore
# 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
Example 2: GitHub API
# 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
π€ Contributing
Contributions are welcome! Here's how to contribute:
Reporting Bugs
- Check existing issues: https://github.com/quotentiroler/mcp-generator-2.0/issues
- Create detailed bug report with:
- OpenAPI spec (sanitized/minimal example)
- Full error message and stack trace
- Steps to reproduce
- Expected vs actual behavior
Suggesting Features
- Open a feature request issue
- Describe the use case and benefit
- Provide examples if applicable
Submitting Pull Requests
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Make your changes
- Run tests:
uv run pytest - Format code:
uv run ruff format . - Commit:
git commit -m 'Add amazing feature' - Push:
git push origin feature/amazing-feature - Open a Pull Request
Development Guidelines
- Follow existing code style (Ruff formatting)
- Add tests for new features
- Update documentation as needed
- Keep commits focused and descriptive
π License
This project is licensed under the Apache License 2.0.
What This Means:
β 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
Why Apache 2.0?
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
π Acknowledgments
- 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.
Made with β€οΈ
