🌦️ AI Weather MCP Server

<p align="center">

</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

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

Each layer has a single responsibility.

---

📂 Project Structure

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

git clone <repository-url>

cd weather-mcp-server

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

pip install -e ".[dev]"

---

🔑 Configuration

Copy:

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

python3 -m weather_mcp.server

---

🐳 Docker

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

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

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