ipma-mcp-server

gabriel20vieira/ipma-mcp-server

3.2

If you are the rightful owner of ipma-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The IPMA Weather MCP Server is a comprehensive Model Context Protocol server providing access to Portuguese weather data from the Instituto Português do Mar e da Atmosfera (IPMA).

Tools
10
Resources
0
Prompts
0

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

  1. 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

  1. 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

  1. 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

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

🌡️ Weather Stations

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

🔍 Seismic Data

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

📚 Reference Data

  1. list_available_cities - List all available locations

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

  2. 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 .
  1. 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.