by quotentiroler
Generate FastMCP 3.x servers directly from OpenAPI 3.0.x/3.1.x (or Swagger 2.0) specifications, delivering production‑ready code with built‑in JWT/OAuth2 authentication, modular sub‑servers, middleware stack, Pydantic validation, auto‑generated tests and optional event store.
MCP Generator 3.1 transforms any OpenAPI specification into a fully functional FastMCP 3.x server. It creates modular Python modules for each API class, injects enterprise‑grade authentication, adds a rich FastMCP middleware stack, and produces test suites, Docker files, and configuration files ready for deployment.
git clone https://github.com/quotentiroler/mcp-generator-3.x.git
cd mcp-generator-3.x
# Recommended dependency manager
uv sync
# Or with pip
pip install -e .
# From a local spec file (default ./openapi.json)
uv run generate-mcp
# Custom file
uv run generate-mcp --file ./my-api.yaml
# Direct URL
uv run generate-mcp --url https://example.com/openapi.json
The command creates a generated_mcp/ directory containing the server code, tests, and a fastmcp.json config.uv run register-mcp ./generated_mcp
export BACKEND_API_TOKEN="your-token"
uv run run-mcp <server-name>
uv run run-mcp <server-name> --mode http --port 8000
python <server_name>_mcp_generated.py --transport stdio
npx @modelcontextprotocol/inspector -e BACKEND_API_TOKEN=your-token python generated_mcp/*_mcp_generated.py
fastmcp.json – enable/disable features such as search‑tools, code‑mode, response limiting, OTEL, etc.| Scenario | Benefit |
|---|---|
| Expose a legacy REST API to AI agents | AI assistants can call generated MCP tools without writing any glue code. |
| Rapid prototyping of AI‑enabled services | One command turns an OpenAPI spec into a runnable server with auth and observability. |
| Enterprise internal APIs | Built‑in JWT/OAuth2 verification and OpenTelemetry make it production‑ready. |
| Testing and debugging | Auto‑generated pytest suite and MCP Inspector provide fast feedback loops. |
| Microservice composition | Modular sub‑servers let you mount only needed parts of a large API. |
Q: Do I need to write any code after generation? A: No. The generator creates a complete server, tests, Dockerfile and configuration. Custom logic can be added by editing the generated modules if needed.
Q: Which Python version is required? A: Python 3.11 or newer.
Q: Can I run the server without the local registry?
A: Yes. Execute the generated script directly (python <name>_mcp_generated.py). The registry (register-mcp) is only a convenience.
Q: How is authentication handled?
A: The generator adds middleware that validates JWTs via JWKS and fully implements OAuth2 flows defined in the OpenAPI security schemes. Enable token validation with --validate‑tokens or via fastmcp.json.
Q: Is there support for caching or persistent storage?
A: Optional flags --enable‑storage and --enable‑caching add a storage backend and cache layer. They are disabled by default for simplicity.
Q: Can I deploy the server to Kubernetes?
A: Yes. Use the provided Dockerfile, push the image, and run it like any container. OpenTelemetry export can be configured in fastmcp.json.
Q: How do I test the generated server from the command line?
A: Use the MCP Inspector CLI, e.g., npx @modelcontextprotocol/inspector --cli python <script> --method tools/list.
🚀 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.
Note: Both JSON and YAML formats are supported. The generator includes a pure Python OpenAPI client generator — no Java or Node.js required.
| 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 |
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.
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" }
}
}
# 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:
generated_mcp/ directoryBy 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?
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 devorfastmcp run, always include:create_serverto properly compose the modular server architecture.
The Inspector will:
http://localhost:6274http://localhost:6277🛠️ Tool Testing
📦 Resource Exploration
💬 Prompt Testing
📊 Debugging
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:
mcp.json structureExample 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'
--validate-tokensFor more details, see the Inspector documentation.
This project installs three CLI commands. Here's a quick cheatsheet.
# 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
# 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
# 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:
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:
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:
Features:
When --validate-tokens is enabled:
Authorization headerConfiguration:
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:
{backend_url}/.well-known/jwks.json{backend_url}backend-apiSimply 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:
git checkout -b feature/amazing-featureuv run pytestuv run ruff format .git commit -m 'Add amazing feature'git push origin feature/amazing-featureThis project is licensed under the Apache License 2.0.
✅ You can:
⚠️ You must:
❌ You cannot:
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
If you find this project useful, please consider giving it a star! ⭐
It helps others discover the tool and motivates continued development.
Made with ❤️
Please log in to share your review and rating for this MCP.
Explore related MCPs that share similar capabilities and solve comparable challenges
by modelcontextprotocol
A Model Context Protocol server for Git repository interaction and automation.
by zed-industries
A high‑performance, multiplayer code editor designed for speed and collaboration.
by modelcontextprotocol
Model Context Protocol Servers
by modelcontextprotocol
A Model Context Protocol server that provides time and timezone conversion capabilities.
by cline
An autonomous coding assistant that can create and edit files, execute terminal commands, and interact with a browser directly from your IDE, operating step‑by‑step with explicit user permission.
by upstash
Provides up-to-date, version‑specific library documentation and code examples directly inside LLM prompts, eliminating outdated information and hallucinated APIs.
by daytonaio
Provides a secure, elastic infrastructure that creates isolated sandboxes for running AI‑generated code with sub‑90 ms startup, unlimited persistence, and OCI/Docker compatibility.
by continuedev
Enables faster shipping of code by integrating continuous AI agents across IDEs, terminals, and CI pipelines, offering chat, edit, autocomplete, and customizable agent workflows.
by github
Connects AI tools directly to GitHub, enabling natural‑language interactions for repository browsing, issue and pull‑request management, CI/CD monitoring, code‑security analysis, and team collaboration.