tejas161/MCP-Server-Weather-App

🌤️ Advanced Weather MCP Server

A sophisticated Model Context Protocol (MCP) server that provides comprehensive real-time weather data using WeatherAPI.com with advanced features like forecasts, air quality monitoring, and weather alerts.

✨ Features

🚀 Real-time Weather API Integration

• Powered by WeatherAPI.com for accurate live weather data
• Supports any city worldwide with precise location data
• Comprehensive weather information including current conditions, forecasts, and air quality

🌍 Advanced Weather Data

• Current Weather: Temperature, humidity, pressure, wind, visibility, UV index
• 3-Day Forecast: Daily predictions with astronomical data
• Hourly Forecasts: Up to 24-hour detailed predictions
• Air Quality: Real-time pollution levels and health indices
• Weather Alerts: Severe weather warnings and notifications

⚡ Performance Optimizations

• Parallel requests for multiple cities
• Smart error handling with detailed error messages
• Direct API calls for real-time data

🛠️ Enhanced Functionality

• Single city weather: Complete weather profile for any location
• Multiple cities: Batch weather requests for efficiency
• Hourly forecasts: Detailed hour-by-hour predictions
• Real-time data: Always fresh weather information

📊 Rich Weather Data Structure

{
  "city": "London",
  "region": "City of London, Greater London",
  "country": "United Kingdom",
  "current": {
    "temp": "24.4°C",
    "condition": "Sunny",
    "humidity": "61%",
    "windSpeed": "8.3 km/h",
    "uvIndex": 6.2
  },
  "airQuality": {
    "pm2_5": 8.3,
    "usEpaIndex": 1
  },
  "forecast": [
    {
      "date": "2025-06-29",
      "maxTemp": "30.5°C",
      "minTemp": "17.6°C",
      "condition": "Sunny",
      "chanceOfRain": "0%"
    }
  ],
  "alerts": []
}

🚀 Quick Start

Prerequisites

• Node.js 18+ (for built-in fetch API)
• pnpm (package manager)

Installation

# Install dependencies
pnpm install

# Start the server
pnpm start

# Or run in development mode with auto-restart
pnpm dev

🔑 API Key Setup

Required: Get a free API key from WeatherAPI.com:

1. Sign up at WeatherAPI.com
2. Get your free API key (1M requests/month)
3. Set the environment variable:

# Set environment variable
export WEATHER_API_KEY="your_api_key_here"

# Or create a .env file
echo "WEATHER_API_KEY=your_api_key_here" > .env

Note: The server requires a valid API key to function. No demo mode available.

🛠️ Available Tools

1. getWeatherDataByCityName

Get comprehensive weather data for a single city including current conditions, 3-day forecast, air quality, and alerts.

Parameters:

• city (string): City name (required, minimum 1 character)

Returns:

• Current weather conditions
• 3-day forecast with astronomical data
• Air quality measurements
• Weather alerts (if any)
• Location details

Example Usage:

{
  "city": "London"
}

2. getWeatherDataForMultipleCities

Get weather data for multiple cities simultaneously with parallel processing for efficiency.

Parameters:

• cities (array): Array of city names (required, minimum 1 city)

Example Usage:

{
  "cities": ["London", "Paris", "Tokyo", "New York"]
}

3. getHourlyForecast

Get detailed hourly weather forecast for up to 24 hours.

Parameters:

• city (string): City name (required)
• hours (number): Number of hours to forecast (optional, default: 12, max: 24)

Returns:

• Hourly temperature, conditions, and weather details
• Rain probability and wind information
• UV index and feels-like temperature

Example Usage:

{
  "city": "Mumbai",
  "hours": 24
}

🔧 Technical Details

Architecture

• MCP Protocol: Uses Model Context Protocol for seamless integration
• Async/Await: Modern JavaScript async patterns
• Error Boundaries: Comprehensive error handling
• Type Safety: Zod schema validation for inputs
• Real-time API: Direct WeatherAPI.com integration for fresh data

Error Handling

• API Errors: Graceful handling of 404, 401, and other HTTP errors
• Network Issues: Fallback to demo data on network failures
• Input Validation: Zod schema validation for all inputs
• Detailed Logging: Console logging for debugging

📈 Performance Features

Parallel Processing

Multiple city requests are processed concurrently using Promise.all():

// All cities are fetched simultaneously
const results = await Promise.all(weatherPromises);

Real-time Data Processing

// Direct API call for fresh weather data
const weatherData = await makeWeatherAPICall(normalizedCity);
return weatherData;

🌍 Global Coverage

WeatherAPI.com provides weather data for:

• 3+ million locations worldwide
• Real-time conditions updated every 15 minutes
• Historical weather data (with paid plans)
• Marine weather for coastal areas
• Astronomy data (sunrise, sunset, moon phases)

🐛 Troubleshooting

Common Issues

1. "WEATHER_API_KEY environment variable is required" error

# Solution: Set your WeatherAPI.com API key
export WEATHER_API_KEY="your_actual_api_key"

# Verify it's set
echo $WEATHER_API_KEY

2. "Invalid city name" error

# Solution: Check city name spelling or try alternative formats
# Examples: "New York", "London, UK", "Mumbai, India"

3. "API key access denied" error

# Solution: Check your WeatherAPI.com subscription status
# Free plan: 1M requests/month
# Paid plans: Higher limits + additional features

4. Server not starting

# Check Node.js version (required: 18+)
node --version

# Reinstall dependencies
rm -rf node_modules pnpm-lock.yaml
pnpm install

🔮 Future Enhancements

• Extended Forecasts: 7-10 day weather predictions
• Historical Weather: Access to past weather data
• Marine Weather: Ocean and coastal weather conditions
• Weather Maps: Radar and satellite imagery
• Bulk Location Import: CSV/JSON file processing
• Response Caching: Optional caching layer for high-traffic scenarios
• Rate Limiting: Smart API call throttling and queuing
• Weather Webhooks: Push notifications for weather changes
• Custom Alerts: User-defined weather condition triggers
• Weather Analytics: Historical trends and statistics

📄 License

ISC License

🤝 Contributing

Pull requests are welcome! Please ensure your code follows the existing patterns and includes appropriate error handling.