Weather Aggregator

AI-powered weather aggregation from 6 sources with intelligent deduction using GPT-5-mini. Works as both a REST API for web apps and an MCP Server for AI assistants (Claude, Cursor, etc.).

✨ Features

• 🌤️ Multi-source aggregation - Open-Meteo, OpenWeatherMap, WeatherAPI, Visual Crossing, MET Norway (Yr.no), DWD (Bright Sky)
• 🤖 AI-powered deduction - GPT-5-mini analyzes differences and deduces most accurate values
• 🔌 Dual Mode - Runs as REST API (FastAPI) or MCP Server (FastMCP)
• 🎨 Ambient theming - Dynamic gradients based on weather/time (sunny, rainy, storm, night, fog, sandstorm, blizzard, aurora...)
• 🧠 Advanced Data Processing - Uses EWMA (Exponential Smoothing) for forecast curves and Kalman Filter for sensor fusion
• 📊 Confidence scores - Based on source agreement (0-1)
• 📅 Forecasts - Daily (up to 16 days) + Hourly (24 hours)
• 🌅 Astronomy - Sunrise/sunset, moon phases
• 🌍 Multi-language - EN, CZ
• 📍 Geolocation - Automatic location detection with reverse geocoding (shows city name, not coordinates)
• 🚀 Smart Caching - Redis-backed caching for geocoding (24h), weather data (30m), and aurora (1h)
• 🛡️ Security - Rate limiting, security headers, and input sanitization
• 🌌 Aurora forecast - Real-time aurora borealis visibility prediction from NOAA data

🚀 Quick Start

1. Configure API Keys

cp .env.example .env

Edit .env:

# Required for AI deduction
OPENAI_API_KEY=sk-...

# Weather providers (add keys to enable more sources)
OPENWEATHERMAP_API_KEY=your_key  # openweathermap.org
WEATHERAPI_KEY=your_key          # weatherapi.com
VISUALCROSSING_KEY=your_key      # visualcrossing.com

2. Install Dependencies

This project uses uv for dependency management.

# Windows
curl -LsSf https://astral.sh/uv/install.ps1 | powershell -c -

# Install project dependencies
uv sync

3. Run Application

Option A: Run as MCP Server (for AI Assistants)

Connect this server to your MCP client (Cursor, Claude Desktop, etc.).

# Run directly
uv run mcp-weather

# OR via python module
uv run python -m src.server

#### Option C: Run with Docker (Recommended)

Full stack (Backend + Frontend + Redis) in one command:

```bash
docker-compose up --build

• Frontend: http://localhost:3000
• API: http://localhost:8000
• Redis: localhost:6379

### 5. Configure Claude Desktop

To use this server with Claude Desktop, edit your config file:
- **Windows**: `C:\Users\USERNAME\AppData\Roaming\Claude\claude_desktop_config.json`
- **Mac/Linux**: `~/Library/Application Support/Claude/claude_desktop_config.json`

Add the following configuration (adjust path to your project):

```json
{
  "mcpServers": {
    "weather": {
      "command": "C:\\Path\\To\\mcp-weather\\.venv\\Scripts\\python.exe",
      "args": [
        "-m",
        "src.server"
      ],
      "cwd": "C:\\Path\\To\\mcp-weather",
      "env": {
        "PYTHONPATH": "C:\\Path\\To\\mcp-weather"
      }
    }
  }
}

Note: The PYTHONPATH environment variable is crucial for the server to find the src module correctly.

Available MCP Tools:

• search_location(query) - Find coordinates for a city
• get_current_weather(location_name) - Get current weather + AI summary
• get_weather_forecast(location_name, days) - Full forecast + AI deduction
• get_weather_by_coordinates(lat, lon) - Weather for exact location
• get_ambient_theme(location_name) - Get UI theme colors for current weather
• get_aurora_forecast(location_name) - Aurora Borealis forecast & visibility

Option B: Run as REST API (for Frontend)

Starts the FastAPI server on http://localhost:8000.

# Run directly
uv run mcp-weather-api

# OR via python module
uv run python -m src.api

4. Run Frontend

cd frontend
npm install
npm run dev

Open http://localhost:3000 🚀

📡 API Endpoints (REST Mode)

Endpoint	Method	Description
/search	POST	Search locations by name
/weather/current	POST	Current weather + AI summary
/weather/forecast	POST	Full forecast + AI analysis
/weather/coordinates	POST	Weather by lat/lon (auto-resolves city name)
/aurora	POST	Aurora borealis forecast from NOAA
/theme	POST	Get ambient theme colors

Example Request

curl -X POST http://localhost:8000/weather/forecast \
  -H "Content-Type: application/json" \
  -d '{"location_name": "Prague"}'

Response includes:

• current - Aggregated current weather
• daily_forecast - 7-day forecast
• hourly_forecast - 24-hour forecast
• ai_summary - AI reasoning about the weather
• confidence - 0-1 score based on source agreement
• sources - List of providers used
• ambient_theme - Theme name + gradient colors

🏗️ Tech Stack

Component	Technology
Backend	Python 3.14+, uv
API Framework	FastAPI (REST)
MCP Framework	FastMCP (MCP Server)
Frontend	Next.js 16.1.4, Tailwind v4, shadcn/ui
AI	OpenAI GPT-5-mini
Weather	Open-Meteo (free), OpenWeatherMap, WeatherAPI, Visual Crossing

📁 Project Structure

mcp-weather/
├── src/
│   ├── api.py           # FastAPI REST server
│   ├── server.py        # MCP Server (FastMCP)
│   ├── aggregator.py    # AI weather aggregation logic
│   ├── models.py        # Pydantic data models
│   └── providers/       # Weather API providers
├── frontend/            # Next.js app
│   └── src/
│       ├── app/
│       ├── components/weather/
│       └── lib/
├── .env                 # API keys
├── pyproject.toml       # Python dependencies
└── uv.lock              # Lock file

🔮 Future Plans

• NOAA Aviation Weather - METARs, TAFs, aviation advisories
• NOAA Marine Weather - Ocean/coastal forecasts
• NOAA Solar/Space - Enhanced UV index and solar radiation data

License

Copyright (c) 2026 Tomáš Stark

All rights reserved.

This code is provided for viewing purposes only. You may not copy, modify, distribute, or use this code, in whole or in part, without explicit written permission from the author.