OpenAPI MCP server

This MCP server dynamically translates OpenAPI specifications into standardized Model Context Protocol (MCP) tools, resources, and prompts, enabling AI agents to easily interact with external APIs without custom wrappers.

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

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

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

Usage

Quick Start Examples

Option 1: Test with Norwegian Weather API

# 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

Option 2: 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

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?"
• Claude will use the weather_get__compact tool automatically!

Running Multiple API Servers

# 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

Advanced Configuration

Authentication Options

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 Variables

Core Configuration

OAuth2 Authentication

Username/Password Authentication

MCP HTTP Transport (Recommended)

Examples & 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

❌ RequestHandler.prepare_request() missing arguments

# Solution: Use fastmcp_server.py instead of server.py
python src/fastmcp_server.py  # ✅ Correct

❌ 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 add this MCP server to 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 > MCP and click "Add new global MCP server".

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

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

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 explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.