README.md•8.06 kB
# 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
```bash
npm install
```
## Usage
### Development
```bash
npm run dev
```
### Production
```bash
npm start
```
### Build
```bash
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
```bash
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
1. Select the `get-weather` tool from the available tools list
2. Enter a city name (e.g., "New York", "London", "Tokyo")
3. Click "Call Tool" to see current weather data
**get-forecast**: Get 7-day weather forecast
1. Select the `get-forecast` tool from the available tools list
2. Enter a city name
3. Click "Call Tool" to see 7-day forecast with daily temperatures and sunrise/sunset times
**get-air-quality**: Get air pollution data
1. Select the `get-air-quality` tool from the available tools list
2. Enter a city name
3. 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:
```json
{
"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:
```json
{
"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:
```json
{
"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