# Weather MCP Agent

## Introduction

This project was built by **Yehya Abou Khechfe**.

The project is a **Weather MCP Agent** that retrieves current weather conditions and forecasts for any city, using the [OpenWeatherMap API](https://openweathermap.org/api).

The MCP server exposes weather tools that can be consumed in multiple ways:
- Connected to **Ollama** (local LLM) for natural-language interaction — see [`ollama_weather_mcp/ollama_mcp_client.py`](./ollama_weather_mcp/ollama_mcp_client.py) and [`ollama_weather_mcp/ollama_mcp_server.py`](./ollama_weather_mcp/ollama_mcp_server.py).
- Connected to **Claude Desktop** — add the server to your Claude configuration file (`claude_desktop_config.json`) as described below.
- A **simple client with no LLM integrated**, used for testing the server directly — see [`weather_mcp/mcp_client.py`](./weather_mcp/mcp_client.py) and [`weather_mcp/mcp_server.py`](./weather_mcp/mcp_server.py).

## Project Structure

```
wheather-mcp-agent/
├── ollama_weather_mcp/
│   ├── ollama_mcp_client.py     # Interactive client powered by Ollama
│   └── ollama_mcp_server.py     # MCP server extended with a prompt for Ollama
├── weather_mcp/
│   ├── __init__.py
│   ├── mcp_client.py            # Simple client (no LLM) for testing the server
│   └── mcp_server.py            # Core MCP server exposing the weather tools
├── .env                         # Environment variables (OpenWeatherMap API key)
├── main.py
├── pyproject.toml
└── README.md
```

## Prerequisites

- **Python** 3.10+
- **[uv](https://docs.astral.sh/uv/)** — used as the package and project manager
- **[Ollama](https://ollama.com/)** installed and running locally, with a pulled model (e.g. `llama3`)
- **`mcp[cli]`** — the MCP Python SDK
- **`httpx`** — for async HTTP requests to the OpenWeatherMap API
- **`python-dotenv`** — for loading environment variables from `.env`
- An **OpenWeatherMap API key** — get one at [openweathermap.org/api](https://openweathermap.org/api)

### Installing dependencies with `uv`

```bash
uv sync
```

### Setting up your `.env` file

Create a `.env` file at the project root:

```
OPENWEATHER_API_KEY=your_api_key_here
```

## Connecting to Claude Desktop

To use this MCP server with Claude Desktop, add it to your Claude configuration file (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": ["run", "--directory", "C:\\path\\to\\wheather-mcp-agent", "weather_mcp/mcp_server.py"]
    }
  }
}
```

Restart Claude Desktop after saving the configuration — the weather tools should then appear as available tools in a new conversation.

## Running the Ollama-powered client

```bash
uv run .\ollama_weather_mcp\ollama_mcp_client.py
```

### Example session

```
[INFO] Server-client connection initialized
Weather Assistant — ask about current conditions or the forecast for any city.
You can also ask general questions.
Type 'q', 'exit', or 'quit' to leave.
You: what is the current weather in paris
[INFO] Requesting Ollama to extract tool and arguments...
Current weather in Paris, FR: clear sky, 32.79°C (feels like 31.48°C), ranging from 32.3°C to 35.03°C, with 28% humidity.
You: and tomorrow ?
[INFO] Requesting Ollama to extract tool and arguments...
--------------------
Weather Forecast in Paris, FR
2026-07-29 12:00:00 — 33.5°C, clear sky
2026-07-29 15:00:00 — 35.88°C, clear sky
2026-07-29 18:00:00 — 37.16°C, clear sky
2026-07-29 21:00:00 — 30.5°C, clear sky
2026-07-30 00:00:00 — 25.28°C, clear sky
2026-07-30 03:00:00 — 22.37°C, scattered clouds
2026-07-30 06:00:00 — 21.97°C, broken clouds
2026-07-30 09:00:00 — 24.71°C, overcast clouds
2026-07-30 12:00:00 — 28.47°C, overcast clouds
2026-07-30 15:00:00 — 33.05°C, clear sky
--------------------
You: what is the capital of lebanon
[INFO] Requesting Ollama to extract tool and arguments...
[INFO] Requesting Ollama to answer a general question ...
Answer: The capital of Lebanon is Beirut (بيروت).
You:
```

## Running the simple test client (no LLM)

Useful for testing the MCP server's tools directly, without going through an LLM:

```bash
uv run .\weather_mcp\mcp_client.py
```

## Available Tools

| Tool | Description |
|---|---|
| `fetch_current_weather` | Fetches the current weather conditions for a given city. |
| `fetch_weather_forecast` | Fetches the weather forecast (3-hour intervals) for a given city. |