What is Openapi Mcp Generator

openapi-mcp-generator is a Python tool that automatically converts OpenAPI (Swagger, ETAPI) compatible specifications into fully functional Model Context Protocol (MCP) servers, generating Docker-ready implementations with support for SSE/IO communication protocols, authentication, and comprehensive error handling.

Use cases

Use cases include generating MCP servers for RESTful APIs, implementing real-time data streaming applications using SSE, and creating secure API services that require authentication and error handling.

How to use

To use openapi-mcp-generator, clone the repository, install the required dependencies using the Python package manager ‘uv’, and run the generator script with the OpenAPI YAML file as input, specifying the output directory and API URL.

Key features

Key features include conversion of OpenAPI specifications to MCP servers, Docker-ready multi-stage builds, support for multiple authentication methods, choice of SSE or IO communication protocols, comprehensive error handling, built-in rate limiting, async operations, and an extensive test suite.

Where to use

openapi-mcp-generator can be used in various fields such as web development, API development, and microservices architecture, where there is a need to create compliant MCP servers from OpenAPI specifications.

OpenAPI to MCP Server Generator

A Python tool that automatically converts OpenAPI specifications into fully functional Model Context Protocol (MCP) servers. Generates Docker-ready implementations with support for SSE/IO communication protocols, authentication, and comprehensive error handling.

Key features:

• 🔄 OpenAPI to MCP tools/resources conversion
• 🐳 Docker-ready with multi-stage builds
• 🔐 Multiple authentication methods
• ⚡ Async operations & rate limiting
• 📡 SSE/IO communication protocols
• 📦 Modular code structure with package support

Modular Code Structure

The generator has been refactored into a proper Python package while maintaining backward compatibility:

1. Original Entry Point: The generator.py script still works exactly as before
2. Modular Organization: Code is now split into focused modules
3. Package Installation: Can be installed as a proper Python package
4. Same Templates: Uses the exact same templates in the /templates directory
5. Docker Support: Preserves all Docker functionality

You can use the tool in whatever way you prefer:

1. Run generator.py directly (original approach)
2. Install as a package and use mcp-generator command
3. Use the module programmatically in your own Python code

For more details on the modular code structure, see MODULAR_REFACTORING.md.

Features

• Convert OpenAPI specifications to MCP servers
• Docker-ready implementation with multi-stage builds
• Support for multiple authentication methods
• Choice of SSE or IO communication protocols
• Comprehensive error handling and logging
• Built-in rate limiting and security features
• Async operations for optimal performance
• Extensive test suite with coverage reporting

Prerequisites

• Python 3.10+
• Docker (for running the generated server)
• pip or uv (Python package manager)

Installation

From Source

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

# Install as a package (development mode)
pip install -e .

# Or using uv
uv venv
source .venv/bin/activate
uv pip install -e .

Using pip (once published)

pip install openapi-mcp-generator

Usage

# Using the original script (still works the same way)
python generator.py openapi.yaml --output-dir ./output --api-url https://api.example.com

# Using the new modular CLI tool after installation
mcp-generator openapi.yaml --output-dir ./output --api-url https://api.example.com

# Using the python module directly
python -m openapi_mcp_generator.cli openapi.yaml --output-dir ./output

Command Line Options

• openapi_file: Path to the OpenAPI YAML file (required)
• --output-dir: Output directory for the generated project (default: ‘.’)
• --api-url: Base URL for the API
• --auth-type: Authentication type (bearer, token, basic)
• --api-token: API token for authentication
• --api-username: Username for basic authentication
• --api-password: Password for basic authentication

Running the Generated Server

After generating the server, you can build and run it using Docker:

cd output/openapi-mcp-*
./docker.sh build
./docker.sh start --transport=sse --port=8000

Docker Script Options

The generated docker.sh script supports the following commands:

• build: Build the Docker image
• start: Start the container
  • --port=PORT: Set the port (default: 8000)
  • --transport=TYPE: Set transport type: ‘sse’ or ‘io’ (default: sse)
  • --log-level=LEVEL: Set logging level (default: info)
• stop: Stop the container
• clean: Remove the container and image
• logs: View container logs

Project Structure

The modular generator has the following structure:

openapi-mcp-generator/
├── generator.py              # Original entry point (maintained for backward compatibility)
├── mcp_generator.py          # New entry point (uses the modular structure)
├── openapi_mcp_generator/    # Main package (new modular structure)
│   ├── __init__.py           # Package initialization
│   ├── cli.py                # Command-line interface
│   ├── generator.py          # Main generator module
│   ├── generators.py         # Code generators for tools/resources
│   ├── http.py               # HTTP client utilities
│   ├── parser.py             # OpenAPI parser
│   └── project.py            # Project builder
├── templates/                # Original templates directory (used by the modular code)
│   ├── config/
│   ├── docker/
│   ├── server/
│   ├── pyproject.toml
│   └── requirements.txt
├── samples/                  # Sample implementations
├── tests/                    # Test cases
├── LICENSE                   # License file
├── README.md                 # This file
├── pyproject.toml            # Project metadata
└── setup.py                  # Package setup

The modular structure preserves all the existing functionality while making the code more maintainable:

1. The original entry point (generator.py) can still be used as before
2. The existing templates in /templates are used by the new modular code
3. All Docker-related functionality is preserved exactly as it was
4. The project can now be installed as a proper Python package

Sample Implementations

Check out our sample implementations to see the generator in action:

• Trilium Notes ETAPI Server - An MCP server for the Trilium Notes knowledge management system’s ETAPI

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run the test suite
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Usage Examples

1. Using the library without installing (direct from source)

To generate an MCP server from the Elasticsearch 6.1 spec folder:

# Run the original script directly
python generator.py samples/elasticsearch_6.1/api

# Or use the modular entry point
python mcp_generator.py samples/elasticsearch_6.1/api

2. Using the library after installing with pip

First, install the package (from the project root):

pip install .

Then use the CLI tool to convert the Trilium ETAPI spec:

mcp-generator samples/TriliumNext/etapi.openapi.yaml

Or use it programmatically in your own Python code:

from openapi_mcp_generator import generator

generator.generate('samples/TriliumNext/etapi.openapi.yaml')