OpenAPI to Model Context Protocol

You use the OpenAPI to Model Context Protocol (MCP) proxy to automatically convert OpenAPI specifications into MCP tools, resources, and prompts. This lets AI agents access external APIs through a standardized MCP interface without writing custom wrappers, while providing robust transport options and strong typing for production use.

How to use

You run the MCP proxy locally or in your environment, point it at your OpenAPI specification, and then connect your MCP client (for example an AI orchestrator) to the MCP HTTP transport or to the stdio transport via a tool launcher. The server automatically registers API operations as tools, derives prompts and resource schemas, and handles authentication. Use the provided tools to compose requests to the external API simply by invoking the corresponding MCP tool.

Key usage patterns include starting the server with your OpenAPI URL, selecting an MCP transport that fits your client, and then connecting your MCP client to the local server. For HTTP transport, the server exposes a streaming endpoint you can reach from your client. For stdio transport, you launch the MCP server as a child process and feed requests through standard input/output.

How to install

Prerequisites: Python 3.12 and a Python virtual environment. You also need network access to fetch the OpenAPI specification or a local OpenAPI file.

Step-by-step commands to set up and run the server locally:

git clone https://github.com/gujord/OpenAPI-MCP.git
cd OpenAPI-MCP
python3.12 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

Start the server with an OpenAPI URL and the desired server name. You can enable the MCP HTTP transport on a specific port or use the default settings for stdio transport.

OPENAPI_URL="https://api.met.no/weatherapi/locationforecast/2.0/swagger" \
SERVER_NAME="weather" \
MCP_HTTP_ENABLED="true" \
MCP_HTTP_PORT="8001" \
python src/fastmcp_server.py

OPENAPI_URL="https://petstore3.swagger.io/api/v3/openapi.json" \
SERVER_NAME="petstore" \
MCP_HTTP_ENABLED="true" \
MCP_HTTP_PORT="8002" \
python src/fastmcp_server.py

Configuration and security

You can customize authentication, transport, and other settings through environment variables and MCP JSON configuration files. The following sections describe common options and how to apply them.

# Example: Claude Desktop integration (HTTP transport via MCP)
{
  "mcpServers": {
    "weather": {
      "command": "npx",
      "args": ["mcp-remote", "http://127.0.0.1:8001/sse"]
    },
    "petstore": {
      "command": "npx",
      "args": ["mcp-remote", "http://127.0.0.1:8002/sse"]
    }
  }
}

For local usage with a full Python server, you can also run with environment variables set to point to the OpenAPI spec and define authentication as needed (OAuth2 or username/password). Ensure MCP_HTTP_ENABLED is set if you plan to use the HTTP transport.

Examples and Use Cases

Common scenarios include querying weather data and interacting with a Pet Store API through generated MCP tools. For weather, the tools expose concise operations like compact and full weather forecasts, while the Pet Store example provides actions to add pets and search by status.

# Weather example start (HTTP transport)
OPENAPI_URL="https://api.met.no/weatherapi/locationforecast/2.0/swagger" \
SERVER_NAME="weather" \
MCP_HTTP_ENABLED="true" \
MCP_HTTP_PORT="8001" \
python src/fastmcp_server.py

# Pet Store example start (HTTP transport)
OPENAPI_URL="https://petstore3.swagger.io/api/v3/openapi.json" \
SERVER_NAME="petstore" \
MCP_HTTP_ENABLED="true" \
MCP_HTTP_PORT="8002" \
python src/fastmcp_server.py

Available tools

weather_get__compact

Weather forecast for coordinates with a compact response.

weather_get__complete

Detailed weather forecast for coordinates.

weather_get__status

Server status endpoint for weather proxy.

petstore_addPet

Add a new pet to the Pet Store.

petstore_findPetsByStatus

Find pets by their status.

petstore_getPetById

Find a pet by its ID.