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.

Related MCP server: OpenWeatherMap MCP Server

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