IPMA Weather MCP Server

Instructions

Implementation Reference

• weather.py:453-495 (handler)

  The main handler function for the list_available_cities tool. It fetches the list of cities from IPMA API endpoint 'distrits-islands.json', groups them by region (Continental Portugal, Madeira, Azores), formats a string output listing up to 30 continental cities and all islands, using the helper make_ipma_request.
  @mcp.tool() async def list_available_cities() -> str: """List all available Portuguese cities and islands for weather forecasts. Returns a comprehensive list of all locations available in the IPMA database, including district capitals and islands (Madeira and Azores). """ cities_url = f"{IPMA_API_BASE}/distrits-islands.json" cities_data = await make_ipma_request(cities_url) if not cities_data or "data" not in cities_data: return "Unable to fetch cities database." result = f"Available Portuguese Cities and Islands ({len(cities_data['data'])} total)\n\n" # Group by region continente = [] madeira = [] acores = [] for entry in cities_data["data"]: location_info = f"{entry.get('local')} (ID: {entry.get('globalIdLocal')})" region_id = entry.get('idRegiao', 0) if region_id == 1: continente.append(location_info) elif region_id == 2: madeira.append(location_info) elif region_id == 3: acores.append(location_info) result += f"CONTINENTAL PORTUGAL ({len(continente)} locations):\n" result += "\n".join(continente[:30]) if len(continente) > 30: result += f"\n... and {len(continente) - 30} more\n" result += f"\n\nMADEIRA ARCHIPELAGO ({len(madeira)} locations):\n" result += "\n".join(madeira) result += f"\n\nAZORES ARCHIPELAGO ({len(acores)} locations):\n" result += "\n".join(acores) return result
• weather.py:12-20 (helper)

  Helper function used by list_available_cities (and other tools) to make HTTP requests to the IPMA API with error handling and timeout.
  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:453-453 (registration)

  The @mcp.tool() decorator registers the list_available_cities function as an MCP tool.
  @mcp.tool()