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

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:

{
  "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