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:

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

Or use uv for better environment management:

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:

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

3. Test the MCP Server

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

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

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

• Test: Visit http://localhost:8000/docs for the auto-generated OpenAPI schema

• All IPMA tools should appear in the documentation

Docker Alternative:

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

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

License

See the Quickstart tutorial for more information about MCP.