API Reference
Weather MCP provides four main tools for accessing weather data through Claude Desktop. All tools use the Model Context Protocol (MCP) standard.
Available Tools
Weather Data Tools
| Tool | Description | Coverage | |------|-------------|----------| | get_forecast | Get weather forecast for a location | Worldwide | | get_current_conditions | Get current weather conditions | Worldwide | | get_alerts | Get active weather alerts | US Only (NOAA) | | search_location | Search for location coordinates | Worldwide |
Tool Usage
All Weather MCP tools are invoked through natural language queries to Claude. You don't need to call them directly - Claude will automatically use the appropriate tool based on your request.
Example Queries
Forecast Requests:
"What's the weather forecast for Seattle?"
"Will it rain in Tokyo tomorrow?"
"Show me the 7-day forecast for London"
Current Conditions:
"What's the current temperature in New York?"
"Is it sunny in San Francisco right now?"
"Current weather conditions in Miami"
Weather Alerts:
"Are there any weather alerts in Florida?"
"Show weather warnings for Texas"
"Active weather alerts in my area" (if location context is provided)
Location Search:
"Find the coordinates for Central Park"
"Where is Yosemite National Park?"
"Latitude and longitude of the Eiffel Tower"
Claude intelligently selects which tool to use based on your natural language request. You can be as specific or general as you like!
Response Format
All tools return structured data that Claude can interpret and present naturally. Responses typically include:
Forecast Data
- Temperature: High/low temperatures in Celsius and Fahrenheit
- Conditions: Description of weather conditions
- Precipitation: Chance and amount of precipitation
- Wind: Speed and direction
- Humidity: Relative humidity percentage
- Time Range: Forecast period
Current Conditions
- Temperature: Current temperature
- Feels Like: Apparent temperature
- Conditions: Current weather description
- Wind: Current wind speed and direction
- Humidity: Current humidity
- Pressure: Atmospheric pressure
- Visibility: Current visibility
- Timestamp: When data was recorded
Weather Alerts
- Type: Alert category (Warning, Watch, Advisory, etc.)
- Severity: Alert severity level
- Headline: Brief alert description
- Description: Detailed alert information
- Areas: Affected regions
- Effective Time: When alert begins
- Expires Time: When alert ends
Location Data
- Name: Location name
- Coordinates: Latitude and longitude
- Country: Country code
- Region: State/province if applicable
- Type: Location type (city, landmark, etc.)
Error Handling
Weather MCP handles errors gracefully and provides helpful error messages:
Common Error Types
Location Not Found
"Could not find location: [query]"
Solution: Try a more specific location name or use coordinates directly.
Service Unavailable
"Weather service temporarily unavailable"
Solution: Weather MCP automatically falls back to alternative providers.
Invalid Coordinates
"Invalid coordinates provided"
Solution: Ensure latitude is between -90 and 90, longitude between -180 and 180.
Rate Limited
"Rate limit exceeded, please try again later"
Solution: Wait a few minutes before making more requests. This is rare due to built-in caching.
Weather MCP includes automatic retry logic and provider fallback, so most errors are handled transparently.
Data Providers
Weather MCP uses two data providers:
NOAA (National Weather Service)
- Coverage: United States
- Requires Token: Yes (free)
- Strengths: Official US government source, highly accurate, detailed alerts
- Data Updates: Hourly for forecasts, more frequent for alerts
Open-Meteo
- Coverage: Worldwide
- Requires Token: No
- Strengths: Global coverage, no authentication needed, good accuracy
- Data Updates: Hourly
Automatic Provider Selection
Weather MCP automatically chooses the best provider based on location and availability. For US locations with a NOAA token, NOAA is preferred. For international locations or when NOAA is unavailable, Open-Meteo is used.
Caching
Weather MCP caches responses to improve performance and reduce API calls:
- Forecast Data: 30-60 minutes
- Current Conditions: 5-10 minutes
- Alerts: 5 minutes
- Location Searches: 24 hours
Cache duration can be configured using the CACHE_TTL environment variable. See Configuration for details.
Rate Limits
NOAA API
- Requests: No hard limit for reasonable use
- Recommended: < 100 requests per hour
- Weather MCP caching reduces actual API calls significantly
Open-Meteo
- Requests: 10,000 per day for non-commercial use
- Rate: No per-second limit
- Commercial: Requires paid plan
Weather MCP's caching ensures you'll stay well within these limits for normal usage.
Tool-Specific Documentation
For detailed information about each tool, including parameters, response schemas, and examples:
- Get Forecast - Detailed forecast data
- Get Current Conditions - Real-time conditions
- Get Alerts - Weather warnings and alerts
- Search Location - Geocoding and location search
Best Practices
- Be Specific: More specific location queries give better results
- Use Natural Language: Ask Claude naturally - it will figure out which tool to use
- Check Alerts: Always check alerts for severe weather situations
- Cache Awareness: Repeated queries for the same location return cached data quickly
- International Queries: Use city and country for best results outside the US