IPMA Weather MCP Server

Instructions

Implementation Reference

• weather.py:118-156 (handler)

  The main handler function for the 'get_daily_aggregate_forecast' tool. It validates the input day parameter (0-2), fetches aggregated daily weather forecast data from the IPMA API for all Portuguese locations, formats a summary including forecast date, total locations, and sample data from the first 10 locations, returning it as a formatted string.
  @mcp.tool() async def get_daily_aggregate_forecast(day: int = 0) -> str: """Get daily aggregated weather forecast for Portugal (Previsão Meteorológica até 3 dias, agregada por dia). Args: day: Forecast day (0=today, 1=tomorrow, 2=day after tomorrow). Valid range: 0-2 Returns aggregated forecast for all Portuguese locations for the specified day. """ if day < 0 or day > 2: return "Invalid day parameter. Please use 0 (today), 1 (tomorrow), or 2 (day after tomorrow)." forecast_url = f"{IPMA_API_BASE}/forecast/meteorology/cities/daily/hp-daily-forecast-day{day}.json" forecast_data = await make_ipma_request(forecast_url) if not forecast_data or "data" not in forecast_data: return "Unable to fetch daily aggregate forecast data." result = f"""Daily Aggregate Weather Forecast Forecast Date: {forecast_data.get('forecastDate', 'Unknown')} Data Updated: {forecast_data.get('dataUpdate', 'Unknown')} Owner: {forecast_data.get('owner', 'IPMA')} Total Locations: {len(forecast_data['data'])} Sample Forecasts (first 10 locations): """ for location in forecast_data['data'][:10]: result += f""" Location ID: {location.get('globalIdLocal', 'N/A')} Position: {location.get('latitude', 'N/A')}°N, {location.get('longitude', 'N/A')}°E Temperature: {location.get('tMin', 'N/A')}°C - {location.get('tMax', 'N/A')}°C Precipitation Probability: {location.get('precipitaProb', 'N/A')}% Weather Type: {location.get('idWeatherType', 'N/A')} Wind: {location.get('predWindDir', 'N/A')} (Speed Class: {location.get('classWindSpeed', 'N/A')}) ---""" return result
• weather.py:12-20 (helper)

  Supporting helper utility function used by the tool to make asynchronous HTTP requests to the IPMA API endpoints, handling errors and timeouts gracefully.
  async def make_ipma_request(url: str) -> dict[str, Any] | list[dict[str, Any]] | None: """Make a request to the IPMA API with proper error handling.""" async with httpx.AsyncClient() as client: try: response = await client.get(url, timeout=30.0) response.raise_for_status() return response.json() except Exception: return None
• weather.py:118-118 (registration)

  The @mcp.tool() decorator registers the get_daily_aggregate_forecast function as an MCP tool with FastMCP.
  @mcp.tool()