IPMA Weather MCP Server (Python)

A comprehensive Model Context Protocol (MCP) server providing access to Portuguese weather data from IPMA (Instituto Português do Mar e da Atmosfera).

Data Source

All data is provided by IPMA (Instituto Português do Mar e da Atmosfera, I.P.)

• API Documentation: https://api.ipma.pt/
• Weather forecasts are updated twice daily (00 UTC and 12 UTC)
• Times are in UTC (add 0h in winter, +1h in summer for Continental Portugal/Madeira; -1h in winter, 0h in summer for Azores)

Features

This MCP server provides complete access to the IPMA API with the following tools:

🌦️ Weather Forecasts

1. get_forecast - 5-day weather forecast for Portuguese cities

   • Detailed daily forecasts including temperature, precipitation, wind
   • Supports all Portuguese cities and islands (Madeira and Azores)

2. get_daily_aggregate_forecast - Daily aggregated forecast for all locations

   • Get forecasts for all Portugal in a single query
   • Supports up to 3 days (today, tomorrow, day after tomorrow)

⚠️ Weather Warnings

3. get_weather_warnings - Active meteorological warnings (up to 3 days)
   • Warning types: precipitation, wind, fog, maritime agitation, snow, thunderstorms, etc.
   • Awareness levels: green (normal), yellow, orange, red
   • Includes affected areas and time periods

🌊 Sea State

4. get_sea_forecast - Sea state forecast for coastal areas (up to 3 days)
   • Wave height, wave period, wave direction
   • Sea surface temperature
   • Covers all Portuguese coastal locations

🔥 Fire Risk

5. get_fire_risk - Fire risk forecast (up to 2 days)
   • RCM (Risco de Incêndio) classification for all municipalities
   • Risk levels: Low, Moderate, High, Very High, Maximum

☀️ UV Index

6. get_uv_forecast - UV radiation index forecast (up to 3 days)
   • UV index levels from Low to Extreme
   • Protection recommendations included

🌡️ Weather Stations

7. get_station_observations - Meteorological observations from weather stations
   • Last 24 hours of hourly data
   • Temperature, humidity, pressure, wind, precipitation, radiation

🔍 Seismic Data

8. get_seismic_data - Seismic activity information (last 30 days)
   • Coverage: Continental Portugal, Azores, Madeira
   • Filter by region

📚 Reference Data

9. list_available_cities - List all available locations

   • Complete list of cities and islands
   • Grouped by region (Continental, Madeira, Azores)

10. get_weather_type_descriptions - Weather type code descriptions

    • Portuguese and English descriptions
    • Helps interpret weather type IDs in forecasts

Installation

1. Install dependencies:

pip install -e .

2. Configure your MCP client to use this server:

For Claude Desktop, add to your config file:

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

{
    "mcpServers": {
        "weather": {
            "command": "python",
            "args": ["-m", "weather"],
            "cwd": "/path/to/weather-server-python"
        }
    }
}

Or use uv for better environment management:

{
    "mcpServers": {
        "weather": {
            "command": "uv",
            "args": ["run", "weather"],
            "cwd": "/path/to/weather-server-python"
        }
    }
}

Usage Examples

Once configured, you can ask Claude questions like:

• "What's the weather forecast for Lisboa?"
• "Are there any active weather warnings in Portugal?"
• "What's the sea state forecast for Porto coast tomorrow?"
• "Show me the fire risk for today"
• "What are the UV levels for the next 3 days?"
• "Get observations from weather station 1210881"
• "List all available Portuguese cities"
• "What seismic activity has been recorded in the Azores?"

API Coverage

This server implements all main IPMA open data endpoints:

✅ Avisos Meteorológicos até 3 dias
✅ Previsão Meteorológica Diária até 5 dias agregada por Local
✅ Previsão Meteorológica Diária até 3 dias, informação agregada por dia
✅ Informação sismicidade, últimos 30 dias (Açores, Continente, Madeira)
✅ Previsão do Estado do Mar até 3 dias, informação agregada por dia
✅ Previsão do Risco de Incêndio até 2 dias, informação agregada por dia
✅ Previsão do Risco de Ultravioletas até 3 dias (Índice Ultravioleta)
✅ Observação Meteorológica de Estações (dados horários, últimas 24 horas)

Integrating with Open WebUI

The IPMA MCP server can be integrated with Open WebUI (v0.6+) using mcpo (MCP-to-OpenAPI proxy), which bridges the stdio-based MCP server to REST endpoints accessible by Open WebUI.

Quick Start with install.sh

We provide an installation helper script to set up the environment:

# Make the script executable
chmod +x install.sh

# Run the installation
./install.sh

The script will:

• Install uv if not already present
• Create a virtual environment
• Install all dependencies
• Verify the installation

Manual Setup

1. Prerequisites

• Open WebUI installed and running (e.g., via Docker):

  docker run -d -p 3000:8080 --add-host=host.docker.internal:host-gateway \
    -v open-webui:/app/backend/data \
    -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \
    --name open-webui --restart always \
    ghcr.io/open-webui/open-webui:main
  

• Python 3.10+ with uv (install via curl -LsSf https://astral.sh/uv/install.sh | sh)
• Clone this repository

2. Set Up Virtual Environment

cd /path/to/ipma-mcp-server
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .

3. Test the MCP Server

Run the server directly (it uses stdio transport by default):

uv run python weather.py

This starts the MCP server locally. Press Ctrl+C to stop.

4. Launch mcpo Proxy

Install mcpo (Open WebUI's official MCP-to-OpenAPI proxy):

uv tool install mcpo

Proxy the MCP server to OpenAPI on port 8000 (use a secure API key):

uvx mcpo --port 8000 --api-key "your-secret-key" -- uv run python weather.py

• Test: Visit http://localhost:8000/docs for the auto-generated OpenAPI schema
• All IPMA tools should appear in the documentation

Docker Alternative:

docker run -p 8000:8000 -v /path/to/ipma-mcp-server:/app \
  ghcr.io/open-webui/mcpo:main \
  --api-key "your-secret-key" -- python /app/weather.py

5. Add to Open WebUI

• Open your Open WebUI instance (e.g., http://localhost:3000)
• Go to Settings (gear icon) > Tools (or Admin Panel > External Tools if admin)
• Click + Add Tool Server
• Configure:
  • Type: OpenAPI (or MCP Streamable HTTP if available)
  • URL: http://localhost:8000 (full base URL)
  • Auth: Bearer token with your API key (your-secret-key)
• Save and restart Open WebUI if prompted

Integration Architecture

Open WebUI (Port 3000)
    ↓ HTTP REST calls
mcpo Proxy (Port 8000)
    ↓ stdio JSON-RPC
IPMA MCP Server (weather.py)
    ↓ HTTPS
IPMA API (api.ipma.pt)

For full MCP documentation, see the Open WebUI MCP Guide.

License

See the Quickstart tutorial for more information about MCP.