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

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)
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

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

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

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

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

🌡️ Weather Stations

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

🔍 Seismic Data

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

📚 Reference Data

list_available_cities - List all available locations
- Complete list of cities and islands
- Grouped by region (Continental, Madeira, Azores)
get_weather_type_descriptions - Weather type code descriptions
- Portuguese and English descriptions
- Helps interpret weather type IDs in forecasts

Installation

Install dependencies:

pip install -e .

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.