OpenAPI-MCP

A zero-configuration tool for integrating Model Context Protocol (MCP) servers with any OpenAPI-compliant application.

Features

• Magical integration - Instantly create an MCP server from any OpenAPI specification with zero configuration
• Automatic discovery - All API endpoints are automatically converted to MCP tools
• Documentation preservation - API documentation is automatically converted to MCP tool descriptions
• Framework agnostic - Works with any API framework that supports OpenAPI (FastAPI, Flask, Django, etc.)
• Zero manual setup - No need to create MCP tools manually, everything is done automatically

Installation

We recommend using uv, a fast Python package installer:

uv add openapi-mcp

Alternatively, you can install with pip:

pip install openapi-mcp

For detailed installation instructions and alternative methods, see INSTALL.md.

Basic Usage

The simplest way to use OpenAPI-MCP is to point it at your OpenAPI specification:

from openapi_mcp import create_mcp_server, serve_mcp

# Just point it at your OpenAPI spec and it does everything automatically
serve_mcp(
    create_mcp_server("https://your-api.com/openapi.json"),
    host="127.0.0.1", 
    port=8000
)

# That's it! Your MCP server is now running with all API endpoints available as tools

If you're using FastAPI, it's even easier:

from fastapi import FastAPI
from openapi_mcp import add_mcp_server

# Your FastAPI app
app = FastAPI()

# Add some endpoints
@app.get("/hello/{name}")
async def hello(name: str):
    """Say hello to someone"""
    return {"message": f"Hello, {name}!"}

# One line to add an MCP server - everything is automatic!
add_mcp_server(app, mount_path="/mcp")

# That's it! Your auto-generated MCP server is now available at `https://app.base.url/mcp`

OpenAPI-MCP is framework-agnostic and works with any API that has an OpenAPI specification:

# Flask with OpenAPI spec
from flask import Flask
from openapi_mcp import create_mcp_server, serve_mcp

# Use your existing OpenAPI specification from any framework
openapi_url = "http://your-flask-app.com/swagger.json"  # URL to your OpenAPI spec

# Create the MCP server from the OpenAPI spec
mcp_server = create_mcp_server(openapi_url)

# Serve the MCP server
serve_mcp(mcp_server, host="127.0.0.1", port=8000)

How It Works

1. OpenAPI-MCP reads your OpenAPI specification
2. It automatically discovers all endpoints and their parameters
3. It automatically converts each endpoint into an MCP tool
4. It automatically generates descriptions, schemas, and examples for each tool
5. It automatically handles HTTP requests to your API when tools are called

No manual tool creation, no boilerplate code, no configuration needed!

Examples

OpenAPI Specification Example:

from openapi_mcp import create_mcp_server, serve_mcp

# Just point it at any OpenAPI specification URL
mcp_server = create_mcp_server("https://api.example.com/openapi.json")

# Start the server
if __name__ == "__main__":
    serve_mcp(mcp_server, host="127.0.0.1", port=8000)

Framework-Specific Examples

FastAPI Example:

from fastapi import FastAPI
from openapi_mcp import add_mcp_server

app = FastAPI(title="Simple API")

@app.get("/hello/{name}")
async def hello(name: str):
    """Say hello to someone"""
    return {"message": f"Hello, {name}!"}

# Just one line to add an MCP server - no configuration needed!
add_mcp_server(app, mount_path="/mcp")

Express.js (Node.js) Example:

For Express.js or other non-Python frameworks, you can run OpenAPI-MCP as a standalone service:

# Using the command-line tool with an OpenAPI specification
openapi-mcp serve https://your-express-app.com/api-docs/swagger.json

This will start an MCP server that proxies requests to your Express.js API based on the OpenAPI specification.

Connecting to the MCP Server

Once your MCP server is running, you can connect to it with any MCP client, such as Claude:

1. Run your application
2. In Claude, use the URL of your MCP server endpoint (e.g., http://localhost:8000/mcp)
3. Claude will discover all available tools and resources automatically

Advanced Options (Optional)

While OpenAPI-MCP is designed to work automatically with zero configuration, there are a few optional settings available if you need more control:

from openapi_mcp import create_mcp_server, serve_mcp

# Create the MCP server with optional customizations
mcp_server = create_mcp_server(
    "https://your-api.com/openapi.json",
    name="My Custom API MCP",                        # Custom name for the MCP server
    base_url="https://your-api.com",                 # Base URL for API requests
    describe_all_responses=True,                     # Include error response schemas in tool descriptions
    describe_full_response_schema=True,              # Include detailed response schemas
)

# You can also register custom functions directly with the MCP server
from mcp.types import ToolDefinition

def get_server_time() -> str:
    """Get the current server time."""
    from datetime import datetime
    return datetime.now().isoformat()

# Register the function as a tool
mcp_server.register_tool(
    ToolDefinition(
        name="get_server_time",
        description="Get the current server time.",
        implementation=get_server_time
    )
)

# Serve the MCP server
serve_mcp(mcp_server, host="127.0.0.1", port=8000)

Development and Contributing

If you're interested in contributing to OpenAPI-MCP:

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

# Create a virtual environment and install dependencies with uv
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv add -e ".[dev]"

# Run tests
uv run pytest

For more details about contributing, see CONTRIBUTING.md.

Requirements

• Python 3.10+
• uv

License

MIT License. Copyright (c) 2024 Tadata Inc.

About

Developed and maintained by Tadata Inc.