# 🌦️ AI Weather MCP Server

<p align="center">

![Python](https://img.shields.io/badge/Python-3.13%2B-blue)
![MCP](https://img.shields.io/badge/Model_Context_Protocol-MCP-green)
![FastMCP](https://img.shields.io/badge/FastMCP-Latest-orange)
![Docker](https://img.shields.io/badge/Docker-Ready-2496ED)
![Tests](https://img.shields.io/badge/Tests-Pytest-success)
![License](https://img.shields.io/badge/License-MIT-lightgrey)

</p>

A **production-grade Model Context Protocol (MCP) server** that combines **real-time weather data** with **LLM-powered reasoning** to deliver intelligent weather insights instead of raw numbers.

Built to demonstrate production backend engineering, clean architecture, MCP development, external API integration, asynchronous programming, Dockerization, testing, and AI reasoning.

---

# ✨ Features

## 🌤 Weather Tools

- Current Weather
- Weather Forecast
- Air Quality
- UV Index
- Sunrise & Sunset

## 🤖 AI Tools

- Clothing Recommendation
- Weather Summary
- Travel Advice
- Outdoor Activity Recommendation
- AI Weather Advisory

The guiding principle is:

> **Weather APIs provide facts. The LLM provides reasoning.**

The model never invents weather information.

---

# 🏗 Architecture

```text
MCP Client
     │
     ▼
MCP Tools
     │
     ▼
Services
     │
     ▼
Clients
 ├── Weather APIs
 └── LLM Provider
```

Each layer has a single responsibility.

---

# 📂 Project Structure

```text
src/weather_mcp/
├── server.py
├── config.py
├── logging_config.py
├── exceptions.py
├── models/
├── clients/
├── services/
└── tools/
```

---

# 🧠 Design Decisions

## Two Weather Providers

The project combines OpenWeatherMap with Open-Meteo.

OpenWeatherMap supplies current weather, forecast and air-quality data.

Open-Meteo is used for UV Index because it remains free without requiring a paid One Call subscription.

---

## AI Weather Advisory

`get_weather_alerts()` intentionally produces an **AI-generated advisory**.

It is **not** an official government weather warning.

Instead, the LLM reasons over forecast information to identify potentially concerning conditions such as:

- Heavy rain
- Strong winds
- High temperatures
- Thunderstorms

---

## Swappable LLM

The LLM layer is isolated.

Changing from Groq to OpenAI only requires configuration rather than application changes.

---

# ⚙️ Installation

```bash
git clone <repository-url>

cd weather-mcp-server

python3 -m venv .venv
source .venv/bin/activate

pip install -e ".[dev]"
```

---

# 🔑 Configuration

Copy:

```bash
cp .env.example .env
```

Configure your API keys.

| Variable | Description |
|----------|-------------|
| WEATHER_API_KEY | OpenWeatherMap key |
| LLM_API_KEY | Groq/OpenAI key |
| LLM_PROVIDER | groq/openai |
| LLM_MODEL | Model name |

---

# ▶ Running

```bash
python3 -m weather_mcp.server
```

---

# 🐳 Docker

```bash
docker build -t weather-mcp-server .

docker run -i --env-file .env weather-mcp-server
```

---

Pull the pre-built image directly:

\`\`\`bash
docker pull amankhan1009/weather-mcp-server:latest
docker run -i --env-file .env amankhan1009/weather-mcp-server:latest
\`\`\`

Or build it yourself:

\`\`\`bash
docker build -t weather-mcp-server .
docker run -i --env-file .env weather-mcp-server
\`\`\`

# 🧪 Testing

```bash
pytest
```

The suite uses mocked external services for deterministic tests.

---

# 🔌 MCP Clients

Compatible with:

- Claude Desktop
- MCP Inspector
- Any MCP-compatible client

---

# 📈 Future Improvements

- Official severe weather alerts
- Additional LLM providers
- Response caching
- Streaming responses
- Structured JSON outputs

---

## 👨‍💻 Author

**Md Aman Alam**

LinkedIn: [Md Aman Alam](https://www.linkedin.com/in/md-aman-alam-a04552289/)

If you found this project useful, consider giving it a ⭐ on GitHub.