IPMA Weather MCP Server

# 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: ```bash 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` ```json { "mcpServers": { "weather": { "command": "python", "args": ["-m", "weather"], "cwd": "/path/to/weather-server-python" } } } ``` Or use `uv` for better environment management: ```json { "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: ```bash # 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): ```bash 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** ```bash 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): ```bash 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): ```bash uv tool install mcpo ``` Proxy the MCP server to OpenAPI on port 8000 (use a secure API key): ```bash 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:** ```bash 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](https://docs.openwebui.com/openapi-servers/mcp/). ## License See the [Quickstart](https://modelcontextprotocol.io/quickstart) tutorial for more information about MCP.