IPMA Weather MCP Server

Instructions

Args:
    city_name: Name of the Portuguese city (e.g. Lisboa, Porto, Faro, Aveiro, Braga)

Returns detailed 5-day forecast including temperature, precipitation, wind, and weather type.

Implementation Reference

• weather.py:59-115 (handler)

  The handler function for the 'get_forecast' tool. It is registered via the @mcp.tool() decorator. Takes a city_name parameter, fetches city ID from IPMA API, then retrieves and formats the 5-day weather forecast including temperatures, precipitation, wind, etc.

  @mcp.tool()
  async def get_forecast(city_name: str) -> str:
      """Get 5-day weather forecast for a Portuguese city (Previsão Meteorológica até 5 dias).
  
      Args:
          city_name: Name of the Portuguese city (e.g. Lisboa, Porto, Faro, Aveiro, Braga)
      
      Returns detailed 5-day forecast including temperature, precipitation, wind, and weather type.
      """
      # First, get the global ID for the city
      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 city database."
  
      # Search for the best match
      city_name_lower = city_name.lower()
      best_match = None
      
      for entry in cities_data["data"]:
          local_name = entry.get("local", "").lower()
          if city_name_lower in local_name or local_name in city_name_lower:
              best_match = entry
              break
      
      if not best_match:
          # Return available cities if no match found
          available_cities = [entry.get("local", "") for entry in cities_data["data"][:15]]
          return f"City '{city_name}' not found. Some available cities: {', '.join(available_cities)}"
      
      # Get the forecast using the global ID
      global_id = best_match.get("globalIdLocal")
      forecast_url = f"{IPMA_API_BASE}/forecast/meteorology/cities/daily/{global_id}.json"
      forecast_data = await make_ipma_request(forecast_url)
  
      if not forecast_data or "data" not in forecast_data:
          return "Unable to fetch forecast data for this location."
  
      # Format the forecast data
      city_info = f"5-Day Weather Forecast for {best_match.get('local')}\n"
      city_info += f"Location: {best_match.get('latitude')}°N, {best_match.get('longitude')}°E\n\n"
      
      forecasts = []
      for day in forecast_data["data"][:5]:  # Show next 5 days
          forecast = f"""Date: {day.get('forecastDate', 'Unknown')}
  Max Temperature: {day.get('tMax', 'N/A')}°C
  Min Temperature: {day.get('tMin', 'N/A')}°C
  Precipitation Probability: {day.get('precipitaProb', 'N/A')}%
  Weather Type ID: {day.get('idWeatherType', 'N/A')}
  Wind Direction: {day.get('predWindDir', 'N/A')}
  Wind Speed Class: {day.get('classWindSpeed', 'N/A')}
  Precipitation Intensity Class: {day.get('classPrecInt', 'N/A')}
  """
          forecasts.append(forecast)
  
      return city_info + "---\n".join(forecasts)