Skip to main content

Weather Tools

Get current weather and forecasts for any location.

Provider: Built-in (OpenWeather API)
Authentication: None required (uses platform API key)
Category: Utilities
Credit Cost: 1 credit per request

Overview​

Weather tools provide real-time weather data and forecasts for cities worldwide. Perfect for location-based applications, travel planning, and contextual AI responses.

Available Tools​

Get Weather​

Get current weather conditions for a city.

Tool ID: weather_Get_Weather
Credit Cost: 1 credit

Parameters:

  • city (string, required): Name of the city
    • Do not include state or country
    • Examples: "London", "Tokyo", "New York"
    • For disambiguation, major cities are preferred

Response:

{
  "location": {
    "city": "San Francisco",
    "country": "US",
    "coordinates": {
      "lat": 37.7749,
      "lon": -122.4194
    }
  },
  "timestamp": "2025-11-22T10:30:00Z",
  "temperature": {
    "current": 18,
    "feels_like": 16,
    "min": 15,
    "max": 21,
    "unit": "celsius"
  },
  "humidity": 65,
  "pressure": 1013,
  "wind": {
    "speed": 5.2,
    "direction": 270,
    "unit": "m/s"
  },
  "weather_condition": {
    "main": "Clouds",
    "description": "scattered clouds",
    "icon": "02d"
  },
  "visibility": 10000,
  "clouds": 40,
  "sunrise": "2025-11-22T06:45:00Z",
  "sunset": "2025-11-22T17:15:00Z"
}

Example Usage:

# Python
response = client.call_tool(
    name="weather_Get_Weather",
    arguments={"city": "San Francisco"}
)

temp = response["temperature"]["current"]
condition = response["weather_condition"]["description"]
print(f"It's {temp}°C with {condition}")
# Output: "It's 18°C with scattered clouds"
// TypeScript
const response = await client.callTool({
  name: "weather_Get_Weather",
  arguments: {
    city: "London"
  }
});

console.log(`Temperature: ${response.temperature.current}°C`);
console.log(`Conditions: ${response.weather_condition.description}`);
# cURL
curl -X POST https://api.joinreeva.com/mcp/server_123 \
  -H "Authorization: Bearer mcpk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "weather_Get_Weather",
      "arguments": {
        "city": "Paris"
      }
    },
    "id": 1
  }'

Use Cases:

  • Display current weather in applications
  • Provide weather context to AI responses
  • Location-based recommendations
  • Travel planning assistance
  • Event scheduling considerations

Get Forecast​

Get weather forecast for upcoming days.

Tool ID: weather_Get_Forecast
Credit Cost: 1 credit

Parameters:

  • city (string, required): Name of the city
    • Same format as Get Weather
  • days (integer, optional): Number of forecast days
    • Default: 5
    • Maximum: 7

Response:

{
  "location": {
    "city": "Tokyo",
    "country": "JP"
  },
  "forecast": [
    {
      "date": "2025-11-22",
      "temperature": {
        "min": 12,
        "max": 18,
        "morning": 14,
        "day": 17,
        "evening": 15,
        "night": 13
      },
      "weather": {
        "main": "Clear",
        "description": "clear sky"
      },
      "humidity": 60,
      "wind_speed": 3.5,
      "precipitation_probability": 10
    },
    {
      "date": "2025-11-23",
      "temperature": {
        "min": 11,
        "max": 19,
        "morning": 13,
        "day": 18,
        "evening": 16,
        "night": 12
      },
      "weather": {
        "main": "Clouds",
        "description": "few clouds"
      },
      "humidity": 55,
      "wind_speed": 4.2,
      "precipitation_probability": 20
    }
  ]
}

Example Usage:

# Python - 5-day forecast
response = client.call_tool(
    name="weather_Get_Forecast",
    arguments={
        "city": "Tokyo",
        "days": 5
    }
)

for day in response["forecast"]:
    print(f"{day['date']}: {day['temperature']['max']}°C - {day['weather']['description']}")
// TypeScript - Weekly forecast
const response = await client.callTool({
  name: "weather_Get_Forecast",
  arguments: {
    city: "Berlin",
    days: 7
  }
});

response.forecast.forEach(day => {
  console.log(`${day.date}: ${day.temperature.min}-${day.temperature.max}°C`);
});

Use Cases:

  • Multi-day travel planning
  • Event scheduling
  • Agricultural planning
  • Outdoor activity recommendations
  • Long-term weather trends

Common Patterns​

Weather-Based Recommendations​

# Suggest activities based on weather
weather = client.call_tool(
    name="weather_Get_Weather",
    arguments={"city": "Seattle"}
)

temp = weather["temperature"]["current"]
condition = weather["weather_condition"]["main"]

if condition == "Rain":
    print("🌧️ Indoor activities recommended")
elif temp > 25:
    print("☀️ Great day for the beach!")
elif temp < 5:
    print("🧊 Bundle up! It's cold outside")
else:
    print("👍 Perfect weather for a walk")

Travel Planning Assistant​

# Check weather for multiple destinations
destinations = ["Paris", "London", "Rome"]

for city in destinations:
    forecast = client.call_tool(
        name="weather_Get_Forecast",
        arguments={"city": city, "days": 7}
    )
    
    avg_temp = sum(day["temperature"]["max"] for day in forecast["forecast"]) / 7
    rainy_days = sum(1 for day in forecast["forecast"] if day["precipitation_probability"] > 50)
    
    print(f"{city}:")
    print(f"  Average temp: {avg_temp:.1f}°C")
    print(f"  Rainy days: {rainy_days}/7")

Temperature Conversion with Math Tools​

# Get weather in Celsius, convert to Fahrenheit
weather = client.call_tool(
    name="weather_Get_Weather",
    arguments={"city": "New York"}
)

temp_celsius = weather["temperature"]["current"]

temp_fahrenheit = client.call_tool(
    name="math_Convert_Units",
    arguments={
        "value": temp_celsius,
        "from_unit": "celsius",
        "to_unit": "fahrenheit"
    }
)

print(f"Temperature: {temp_celsius}°C / {temp_fahrenheit['result']:.1f}°F")

Event Planning Decision​

# Should we schedule outdoor event?
event_date = "2025-11-25"
event_city = "Austin"

forecast = client.call_tool(
    name="weather_Get_Forecast",
    arguments={"city": event_city, "days": 7}
)

# Find forecast for event date
event_weather = next(
    day for day in forecast["forecast"] 
    if day["date"] == event_date
)

if event_weather["precipitation_probability"] > 50:
    print("⚠️ High chance of rain - consider indoor venue")
elif event_weather["temperature"]["max"] > 35:
    print("🌡️ Very hot - provide shade and hydration")
else:
    print("✅ Weather looks good for outdoor event!")

Advanced Integration​

Weather-Aware Notifications​

# Send weather-based notifications
def send_weather_alert(city, threshold_temp=35):
    weather = client.call_tool(
        name="weather_Get_Weather",
        arguments={"city": city}
    )
    
    temp = weather["temperature"]["current"]
    condition = weather["weather_condition"]["main"]
    
    if temp > threshold_temp:
        send_notification(
            f"🌡️ Heat Alert: {temp}°C in {city}. Stay hydrated!"
        )
    elif condition in ["Thunderstorm", "Snow"]:
        send_notification(
            f"⚠️ Severe Weather: {condition} in {city}. Stay safe!"
        )

Multi-City Comparison​

# Compare weather across multiple cities
cities = ["New York", "Los Angeles", "Chicago", "Miami"]

comparison = []
for city in cities:
    weather = client.call_tool(
        name="weather_Get_Weather",
        arguments={"city": city}
    )
    
    comparison.append({
        "city": city,
        "temp": weather["temperature"]["current"],
        "condition": weather["weather_condition"]["description"]
    })

# Sort by temperature
comparison.sort(key=lambda x: x["temp"], reverse=True)

print("Warmest to coldest:")
for item in comparison:
    print(f"{item['city']}: {item['temp']}°C - {item['condition']}")

Forecast Summary Report​

# Generate weekly weather summary
def generate_weather_report(city):
    forecast = client.call_tool(
        name="weather_Get_Forecast",
        arguments={"city": city, "days": 7}
    )
    
    temps = [day["temperature"]["max"] for day in forecast["forecast"]]
    conditions = [day["weather"]["main"] for day in forecast["forecast"]]
    
    report = {
        "city": city,
        "avg_temp": sum(temps) / len(temps),
        "min_temp": min(temps),
        "max_temp": max(temps),
        "most_common_condition": max(set(conditions), key=conditions.count),
        "forecast_period": f"{forecast['forecast'][0]['date']} to {forecast['forecast'][-1]['date']}"
    }
    
    return report

Best Practices​

City Name Handling​

  • Use English city names
  • For common names, major cities are prioritized
  • If wrong city is returned, be more specific in your application logic
  • Cache weather data to reduce API calls

Update Frequency​

  • Current weather: Update every 10-30 minutes
  • Forecasts: Update every 1-3 hours
  • Don't query on every user interaction
  • Store and reuse recent results

Error Handling​

  • Handle city not found errors gracefully
  • Provide fallback for API failures
  • Validate city names before querying
  • Consider timezone differences

Performance​

  • Batch queries when possible
  • Cache results appropriately
  • Don't query same city multiple times rapidly
  • Consider user's location for default city

Troubleshooting​

"City not found" Error​

Cause: City name not recognized or ambiguous

Solutions:

  • Check spelling of city name
  • Try major city nearby
  • Use English name for international cities
  • Remove state/country from city parameter

Unexpected City Results​

Cause: Multiple cities with same name

Solutions:

  • Major cities are prioritized automatically
  • Be aware of common city names (e.g., "London" defaults to London, UK)
  • Consider adding disambiguation in your application logic

Data seems delayed​

Cause: Weather data update frequency

Solutions:

  • Weather APIs typically update every 10-15 minutes
  • Forecasts update less frequently
  • This is normal for weather data
  • Check timestamp in response for data age

Integration Examples​

Example 1: Smart Morning Briefing​

# Morning briefing with weather
def morning_briefing(city):
    # Get current weather
    current = client.call_tool(
        name="weather_Get_Weather",
        arguments={"city": city}
    )
    
    # Get 3-day forecast
    forecast = client.call_tool(
        name="weather_Get_Forecast",
        arguments={"city": city, "days": 3}
    )
    
    # Format time
    time = client.call_tool(name="get_current_time")
    formatted_time = client.call_tool(
        name="format_date",
        arguments={
            "date_string": time["iso_format"],
            "format_str": "%A, %B %d"
        }
    )
    
    # Create briefing
    briefing = f"""
Good morning! {formatted_time['formatted']}

Current weather in {city}:
🌡️ {current['temperature']['current']}°C (feels like {current['temperature']['feels_like']}°C)
☁️ {current['weather_condition']['description']}

3-Day Forecast:
"""
    
    for day in forecast['forecast']:
        briefing += f"\n{day['date']}: {day['temperature']['min']}-{day['temperature']['max']}°C"
    
    return briefing

Example 2: Travel Weather Comparison​

# Compare weather for travel destinations
def compare_destinations(cities, travel_dates):
    results = []
    
    for city in cities:
        forecast = client.call_tool(
            name="weather_Get_Forecast",
            arguments={"city": city, "days": 7}
        )
        
        # Calculate average conditions during travel
        relevant_days = [
            day for day in forecast["forecast"]
            if day["date"] in travel_dates
        ]
        
        avg_temp = sum(d["temperature"]["max"] for d in relevant_days) / len(relevant_days)
        rain_chance = max(d["precipitation_probability"] for d in relevant_days)
        
        results.append({
            "city": city,
            "avg_temp": avg_temp,
            "rain_chance": rain_chance,
            "score": avg_temp * (100 - rain_chance) / 100  # Simple scoring
        })
    
    # Sort by score
    results.sort(key=lambda x: x["score"], reverse=True)
    return results

See Also​