Weather MCP Server - Day 10

Overview

Day 10 of the 30-Day RAG Learning Journey focuses on building a Weather MCP Server that integrates with real-time weather APIs. This project combines RAG (Retrieval-Augmented Generation) principles with Location-Based Context Synthesis (LBCS) systems.

Project Structure

day10-weather-mcp/
├── weather_mcp_server.py    # Main MCP server with weather tools
├── test_weather.py          # Test client for API validation
├── requirements.txt         # Python dependencies
├── .env                     # Environment variables (API keys)
├── .env.example            # Template for environment setup
├── README.md               # This file
└── venv/                   # Virtual environment

Features - 5 Weather Tools

1. get_current_weather (location: str)

Returns comprehensive current weather data:

• Temperature
• Feels Like temperature
• Humidity percentage
• Weather description
• Wind speed
• Pressure
• Cloud coverage

# Example usage
location = "London"
units = "metric"  # or "imperial", "standard"

2. get_forecast (location: str, days: int)

Returns 5-day weather forecast with daily highs/lows:

• Daily high temperatures
• Daily low temperatures
• Weather conditions
• Configurable forecast days (1-5)

# Example usage
location = "Paris"
days = 5

3. get_weather_alerts (location: str)

Returns severe weather warnings and alerts (if any):

• Alert event type
• Start/end times
• Alert descriptions
• Severity indicators

# Example usage
location = "New York"

4. compare_locations (location1: str, location2: str)

Returns side-by-side weather comparison:

• Temperature comparison
• Humidity levels
• Wind speeds
• Weather conditions
• Pressure readings

# Example usage
location1 = "London"
location2 = "New York"

5. get_weather_by_coords (lat: float, lon: float)

Returns weather for specific latitude/longitude:

• Temperature at coordinates
• Location name (reverse geocoding)
• All weather parameters
• Pressure, humidity, wind

# Example usage
lat = 51.5074
lon = -0.1278

Tech Stack

• Python 3.11: Core programming language
• MCP 1.25.0: Model Context Protocol for Claude integration
• httpx 0.28.1: Async HTTP client for API calls
• OpenWeatherMap API: Real-time weather data provider
• python-dotenv: Environment variable management
• Async/await patterns: Non-blocking I/O operations

Setup Instructions

1. Prerequisites

• Python 3.8+
• OpenWeather API key (free tier available)
• Virtual environment (recommended)

2. Get API Key

1. Visit OpenWeather API
2. Sign up for a free account
3. Get your API key from the account dashboard
4. Copy your API key

3. Install Dependencies

# Navigate to directory
cd week2-mcp/day10-weather-mcp

# Create and activate virtual environment
python -m venv venv

# Windows
venv\Scripts\activate

# macOS/Linux
source venv/bin/activate

# Install packages
pip install -r requirements.txt

4. Configure Environment

# Copy template
cp .env.example .env

# Edit .env and add your API key
# WEATHER_API_KEY=your_actual_api_key_here

5. Run Server

python weather_mcp_server.py

6. Test Integration

python test_weather.py

API Response Examples

Current Weather (London)

Current Weather in London, GB:

Description: Partly Cloudy
Temperature: 8.5°C
Feels Like: 6.2°C
Humidity: 72%
Wind Speed: 4.5 m/s
Pressure: 1013 hPa
Cloudiness: 40%

Weather Forecast (5-Day)

5-Day Weather Forecast for London:

Date: 2025-12-28
High: 10.2°C | Low: 5.3°C
Conditions: Rainy
--------------------------------------------------

Date: 2025-12-29
High: 9.1°C | Low: 4.8°C
Conditions: Cloudy
--------------------------------------------------

Weather Comparison

Weather Comparison: London vs Paris
============================================================
London               | Paris
------------------------------------------------------------
Temperature:    8.5°C | 9.2°C
Feels Like:     6.2°C | 7.1°C
Humidity:       72%   | 65%
Conditions:     Cloudy| Clear
Wind Speed:     4.5   | 3.2 m/s

Integration with Claude Desktop

To use this MCP server with Claude Desktop:

1. Edit your Claude Desktop configuration file:

   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

2. Add the weather server:

{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": ["C:\\path\\to\\weather_mcp_server.py"]
    }
  }
}

3. Restart Claude Desktop

Learning Concepts

RAG & LBCS Integration

This project demonstrates:

1. Context-Aware Retrieval: Using location data to retrieve relevant weather information
2. Real-time Data Processing: Async handling of API calls
3. MCP Protocol: Integrating external tools with LLMs
4. Error Handling: Graceful degradation when APIs fail
5. Data Formatting: Structured output for LLM consumption

Key Technologies

• asyncio: Asynchronous Python for concurrent requests
• httpx: Async HTTP client for API calls
• OpenWeather API: Real-time weather data provider
• MCP Protocol: Tool integration with Claude
• Type Hints: Full Python type annotations

Usage Examples

Ask Claude

"What's the weather like in Tokyo right now?"

Claude uses get_current_weather tool to retrieve current conditions.

"Compare the weather between London, Paris, and New York"

Claude uses compare_locations tool for side-by-side analysis.

"What will the weather be like in Sydney over the next 5 days?"

Claude uses get_forecast tool to get daily predictions.

"Get the weather at coordinates 51.5074, -0.1278"

Claude uses get_weather_by_coords for precise location weather.

"Are there any weather alerts for Los Angeles?"

Claude uses get_weather_alerts to check for severe weather.

Troubleshooting

API Key Not Working

• Verify your API key is correct in .env
• Check if your OpenWeather account is activated
• Ensure you have enough API call quota
• Wait 10 minutes after creating account before first use

Connection Errors

• Check your internet connection
• Verify OpenWeather API is accessible
• Check firewall settings
• Verify the domain isn't blocked in your region

Import Errors

• Ensure virtual environment is activated
• Reinstall requirements: pip install -r requirements.txt
• Check Python version (3.8+ required)

Tool Not Found Errors

• Restart Claude Desktop after adding server config
• Verify server config JSON is valid
• Check file paths are absolute, not relative

File Descriptions

weather_mcp_server.py

Main MCP server implementation with:

• Tool registration (list_tools)
• Tool execution (call_tool)
• Handler functions for each weather tool
• Async HTTP client setup
• Error handling and logging

test_weather.py

Test client for validating:

• Server startup
• Tool execution
• API connectivity
• Response formatting

requirements.txt

Python package dependencies:

• mcp==1.25.0
• aiosqlite==0.21.0
• python-dotenv==1.0.0
• httpx>=0.27.1
• requests==2.31.0

.env / .env.example

Environment configuration:

• WEATHER_API_KEY: Your OpenWeather API key
• SERVER_PORT: Server port (default 8000)
• LOG_LEVEL: Logging level (INFO, DEBUG, etc.)

Next Steps (Day 11)

• [ ] Add air quality index (AQI) integration
• [ ] Implement weather history retrieval
• [ ] Add UV index and visibility data
• [ ] Create weather-based activity recommendations
• [ ] Build predictive models for weather patterns
• [ ] Add support for severe weather notifications
• [ ] Integrate multiple weather providers
• [ ] Create weather analytics dashboard

Performance Metrics

• Average Response Time: ~500-800ms per API call
• Concurrent Requests: Supports multiple simultaneous queries
• API Rate Limit: Depends on OpenWeather plan (1000/day free)
• Server Memory: ~100MB baseline
• Database: Currently stateless (can add persistent cache)

Resources

• OpenWeather API Documentation
• MCP Specification
• Python asyncio Guide
• httpx Documentation
• Claude API Documentation

Contributing

To extend this project:

1. Add new weather tools in list_tools()
2. Create handler functions in weather_mcp_server.py
3. Add tool calls in call_tool() function
4. Test with test_weather.py
5. Update documentation

Author

Rithwik Nyalam
Date: December 28, 2025
Part of: 30-Day RAG Learning Journey - Week 2

---

Last Updated: December 28, 2025
Status: Production Ready
Version: 1.0.0