MCP Weather Server
A Model Context Protocol (MCP) server that provides detailed weather information for any city using the Open-Meteo API.
Features
- 🌤️ Real-time weather data for any city worldwide
- 📅 7-day weather forecast with daily temperatures and precipitation
- 🌬️ Air quality information including European Air Quality Index
- 📍 Automatic geocoding - just provide a city name
- 🌡️ Current conditions including temperature, humidity, and precipitation
- 📊 Hourly forecast for the next 24 hours
- 🌅 Sunrise and sunset times for planning outdoor activities
- 🎯 Human-readable weather descriptions instead of raw codes
- ⚡ Robust error handling with retry logic and timeouts
- 🛡️ Type-safe with full TypeScript support
- 🎨 Structured JSON output for easy programmatic access
Installation
npm install
Usage
Development
npm run dev
Production
npm start
Build
npm run build
Testing with MCP Inspector
You can test the weather server using the MCP Inspector, a GUI tool for testing MCP servers.
1. Install and Run MCP Inspector
npx -y @modelcontextprotocol/inspector
2. Configure the Server
In the MCP Inspector settings:
- Command:
npx - Arguments:
tsx main.ts
3. Test the Tools
Once connected, you can test all three tools:
get-weather: Get current weather conditions and hourly forecast
- Select the
get-weathertool from the available tools list - Enter a city name (e.g., "New York", "London", "Tokyo")
- Click "Call Tool" to see current weather data
get-forecast: Get 7-day weather forecast
- Select the
get-forecasttool from the available tools list - Enter a city name
- Click "Call Tool" to see 7-day forecast with daily temperatures and sunrise/sunset times
get-air-quality: Get air pollution data
- Select the
get-air-qualitytool from the available tools list - Enter a city name
- Click "Call Tool" to see air quality index and pollutant levels
The inspector will display the JSON response with all the structured data for each tool.
API
The server provides three tools for comprehensive weather and air quality information:
1. get-weather
Get detailed current weather information for any city.
Parameters:
city(string, required): The name of the city to get weather for- Examples: "New York", "London", "Tokyo", "Paris"
2. get-forecast
Get 7-day weather forecast for any city.
Parameters:
city(string, required): The name of the city to get forecast for- Examples: "New York", "London", "Tokyo", "Paris"
3. get-air-quality
Get air pollution data for any city.
Parameters:
city(string, required): The name of the city to get air quality for- Examples: "New York", "London", "Tokyo", "Paris"
Example Outputs
get-weather Output
Returns structured JSON data with current conditions and hourly forecast:
{
"location": {
"name": "New York",
"fullName": "New York, New York, United States",
"latitude": 40.7128,
"longitude": -74.006,
"country": "United States",
"admin1": "New York"
},
"current": {
"time": "2024-01-15T14:30:00",
"formattedTime": "2:30 PM",
"temperature": 22.5,
"formattedTemperature": "22.5°C",
"feelsLike": 24.1,
"formattedFeelsLike": "24.1°C",
"humidity": 65,
"precipitation": 0,
"formattedPrecipitation": "No precipitation",
"weatherCode": 2,
"weatherDescription": "Partly cloudy"
},
"hourly": [
{
"time": "2024-01-15T15:00:00",
"formattedTime": "3:00 PM",
"temperature": 22.8,
"formattedTemperature": "22.8°C",
"precipitation": 0,
"formattedPrecipitation": "No precipitation"
}
],
"raw": {
// Original Open-Meteo API response for compatibility
}
}
get-forecast Output
Returns 7-day forecast with daily temperatures, precipitation, and sunrise/sunset times:
{
"location": {
"name": "New York",
"fullName": "New York, New York, United States",
"latitude": 40.7128,
"longitude": -74.006,
"country": "United States",
"admin1": "New York"
},
"daily": [
{
"date": "2024-01-15",
"formattedDate": "Monday, Jan 15",
"maxTemperature": 25.2,
"formattedMaxTemperature": "25.2°C",
"minTemperature": 18.5,
"formattedMinTemperature": "18.5°C",
"precipitation": 2.1,
"formattedPrecipitation": "2.1mm",
"weatherCode": 3,
"weatherDescription": "Overcast",
"sunrise": "2024-01-15T07:15:00",
"formattedSunrise": "7:15 AM",
"sunset": "2024-01-15T16:45:00",
"formattedSunset": "4:45 PM"
}
],
"raw": {
// Original Open-Meteo API response for compatibility
}
}
get-air-quality Output
Returns air pollution data with European Air Quality Index and pollutant levels:
{
"location": {
"name": "New York",
"fullName": "New York, New York, United States",
"latitude": 40.7128,
"longitude": -74.006,
"country": "United States",
"admin1": "New York"
},
"current": {
"time": "2024-01-15T14:30:00",
"formattedTime": "2:30 PM",
"europeanAqi": 35,
"aqiLevel": "Fair",
"aqiDescription": "Air quality is acceptable",
"pm25": 28,
"pm10": 42,
"no2": 45,
"o3": 32,
"so2": 8
},
"hourly": [
{
"time": "2024-01-15T15:00:00",
"formattedTime": "3:00 PM",
"europeanAqi": 38,
"aqiLevel": "Fair",
"pm25": 30,
"pm10": 45,
"no2": 48,
"o3": 35,
"so2": 9
}
],
"raw": {
// Original Open-Meteo API response for compatibility
}
}
Improvements Made
1. Enhanced Data Structure
- Replaced raw API JSON with structured, processed weather data
- Added both raw values and formatted strings for flexibility
- Included location details with coordinates and full names
- Provided hourly forecast in a structured array format
- Maintained backward compatibility with original API response
2. Robust Error Handling
- Implemented retry logic with exponential backoff
- Added request timeouts to prevent hanging requests
- Better error messages for different failure scenarios
- Graceful handling of city not found errors
3. Type Safety
- Added comprehensive TypeScript interfaces for all API responses
- Proper type checking for geocoding and weather data
- Better IntelliSense support and compile-time error detection
4. Configuration Management
- Centralized configuration object for easy maintenance
- Configurable timeouts, retry counts, and API endpoints
- Easy to modify settings without touching core logic
5. Performance & Reliability
- Request timeout handling (10 seconds)
- Automatic retry for failed requests (up to 3 attempts)
- Proper URL encoding for city names
- Abort controller for request cancellation
6. Data Processing
- Weather code mapping to human-readable descriptions
- Proper formatting for temperatures, precipitation, and times
- Location name formatting with state/province when available
- Timezone-aware time formatting
7. Code Organization
- Separated concerns into utility functions
- Clear function naming and documentation
- Modular design for easy testing and maintenance
- Consistent error handling patterns
Technical Details
- Framework: Model Context Protocol (MCP) SDK
- Language: TypeScript
- APIs: Open-Meteo (geocoding and weather)
- Transport: StdioServerTransport
- Validation: Zod schema validation
- Runtime: Node.js with ES modules
Error Handling
The server handles various error scenarios:
- City not found: Returns a helpful message with spelling suggestions
- Network errors: Retries up to 3 times with exponential backoff
- API errors: Provides user-friendly error messages
- Timeout errors: Aborts requests after 10 seconds
License
ISC