IPMA Weather MCP Server

Instructions

Returns current active weather warnings (Avisos Meteorológicos) including:
- Warning type (precipitation, wind, fog, maritime agitation, etc.)
- Awareness level (green, yellow, orange, red)
- Affected area
- Start and end times

Implementation Reference

• weather.py:23-56 (handler)

  The handler function for the 'get_weather_warnings' tool. Decorated with @mcp.tool() for registration. Fetches weather warnings data from IPMA API, filters active warnings (non-green), and formats them into a readable string output.

  @mcp.tool()
  async def get_weather_warnings() -> str:
      """Get Portuguese meteorological warnings for up to 3 days.
      
      Returns current active weather warnings (Avisos Meteorológicos) including:
      - Warning type (precipitation, wind, fog, maritime agitation, etc.)
      - Awareness level (green, yellow, orange, red)
      - Affected area
      - Start and end times
      """
      warnings_url = f"{IPMA_API_BASE}/forecast/warnings/warnings_www.json"
      warnings_data = await make_ipma_request(warnings_url)
      
      if not warnings_data:
          return "Unable to fetch weather warnings data."
      
      # Filter active warnings (not green level)
      active_warnings = [w for w in warnings_data if w.get("awarenessLevelID") != "green"]
      
      if not active_warnings:
          return "No active weather warnings at this time. All areas are at green (normal) level."
      
      result = "Active Weather Warnings:\n\n"
      for warning in active_warnings:
          result += f"""Area: {warning.get('idAreaAviso', 'N/A')}
  Type: {warning.get('awarenessTypeName', 'N/A')}
  Level: {warning.get('awarenessLevelID', 'N/A').upper()}
  Description: {warning.get('text', 'N/A')}
  Start: {warning.get('startTime', 'N/A')}
  End: {warning.get('endTime', 'N/A')}
  ---
  """
      
      return result

• weather.py:12-21 (helper)

  Helper utility function used by get_weather_warnings to make asynchronous HTTP requests to the IPMA API endpoints with timeout and error handling.

  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:23-23 (registration)

  The @mcp.tool() decorator registers the get_weather_warnings function as an MCP tool on the FastMCP server instance.

  @mcp.tool()

• weather.py:10-10 (helper)

  Constant defining the base URL for IPMA API calls, used in constructing the warnings endpoint URL.

  IPMA_API_BASE = "https://api.ipma.pt/open-data"