OpenAPI MCP server

The OpenAPI to Model Context Protocol (MCP) proxy server translates OpenAPI specifications into MCP tools, allowing AI agents to seamlessly access external APIs without needing custom wrappers. It acts as a bridge between AI models and API services by dynamically converting API operations into standardized tools that AI agents can use.

Installation

Basic Setup

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

Docker Deployment

For a quick start using Docker:

# Start all services (weather + petstore)
./docker-start.sh

# Or manually
docker-compose up --build -d

This runs the Weather API on port 8001 and Petstore API on port 8002.

Usage Examples

Simple Weather API Example

# Activate virtual environment
source venv/bin/activate

# Run weather API server
OPENAPI_URL="https://api.met.no/weatherapi/locationforecast/2.0/swagger" \
SERVER_NAME="weather" \
python src/fastmcp_server.py

HTTP Transport (Recommended for Claude Desktop)

# Start weather API with HTTP transport
source venv/bin/activate && \
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

Multiple API Servers

Run multiple OpenAPI services simultaneously:

# Terminal 1: Weather API
source venv/bin/activate && \
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

# Terminal 2: Petstore API  
source venv/bin/activate && \
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

Claude Desktop Setup

1. Copy the provided configuration

cp claude_desktop_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json

2. Start the weather server

source venv/bin/activate && \
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

3. Test in Claude Desktop

Ask: "What's the weather in Oslo tomorrow?" and Claude will use the weather_get__compact tool automatically!

Advanced Configuration

Configuration Files

HTTP Transport (Recommended)

{
  "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"]
    }
  }
}

With Username/Password Authentication

{
  "mcpServers": {
    "secure_api": {
      "command": "full_path_to_openapi_mcp/venv/bin/python",
      "args": ["full_path_to_openapi_mcp/src/server.py"],
      "env": {
        "SERVER_NAME": "secure_api",
        "OPENAPI_URL": "https://api.example.com/openapi.json",
        "API_USERNAME": "your_username",
        "API_PASSWORD": "your_password"
      },
      "transport": "stdio"
    }
  }
}

With OAuth2 Authentication

{
  "mcpServers": {
    "oauth_api": {
      "command": "full_path_to_openapi_mcp/venv/bin/python",
      "args": ["full_path_to_openapi_mcp/src/server.py"],
      "env": {
        "SERVER_NAME": "oauth_api",
        "OPENAPI_URL": "https://api.example.com/openapi.json",
        "OAUTH_CLIENT_ID": "your_client_id",
        "OAUTH_CLIENT_SECRET": "your_client_secret",
        "OAUTH_TOKEN_URL": "https://api.example.com/oauth/token"
      },
      "transport": "stdio"
    }
  }
}

Environment Configuration

Core Configuration

Variable	Description	Required	Default
OPENAPI_URL	URL to the OpenAPI specification	Yes	-
SERVER_NAME	MCP server name	No	openapi_proxy_server

OAuth2 Authentication

Variable	Description	Required	Default
OAUTH_CLIENT_ID	OAuth client ID	No	-
OAUTH_CLIENT_SECRET	OAuth client secret	No	-
OAUTH_TOKEN_URL	OAuth token endpoint URL	No	-
OAUTH_SCOPE	OAuth scope	No	api

MCP HTTP Transport (Recommended)

Variable	Description	Required	Default
MCP_HTTP_ENABLED	Enable MCP HTTP transport	No	false
MCP_HTTP_HOST	MCP HTTP server host	No	127.0.0.1
MCP_HTTP_PORT	MCP HTTP server port	No	8000
MCP_CORS_ORIGINS	CORS origins (comma-separated)	No	*

Example Use Cases

Norwegian Weather API

# Start weather server
source venv/bin/activate && \
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

Available tools:

• weather_get__compact - Weather forecast for coordinates
• weather_get__complete - Detailed weather forecast
• weather_get__status - Server status

Example usage in Claude:

• "What's the weather in Oslo tomorrow?" → Uses lat=59.9139, lon=10.7522
• "Show me detailed weather for Bergen" → Uses lat=60.3913, lon=5.3221

Pet Store API

# Start petstore server
source venv/bin/activate && \
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:

• petstore_addPet - Add a new pet to the store
• petstore_findPetsByStatus - Find pets by status
• petstore_getPetById - Find pet by ID

Troubleshooting

Common Issues

❌ Claude Desktop doesn't see the tools

# Check configuration location
ls ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Restart Claude Desktop after config changes

❌ Connection refused on port 8001

# Check if server is running
lsof -i :8001

# Check server logs for errors

❌ SSL/TLS errors with OpenAPI URLs

# Update certificates
pip install --upgrade certifi httpx

Testing Tools

Test with mcp-remote:

npx mcp-remote http://127.0.0.1:8001/sse

Check available tools:

curl http://127.0.0.1:8001/health

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "openapi_service" '{"command":"npx","args":["mcp-remote","http://127.0.0.1:8001/sse"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "openapi_service": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "http://127.0.0.1:8001/sse"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "openapi_service": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "http://127.0.0.1:8001/sse"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect