# weather-mcp-pro

An MCP (Model Context Protocol) server that exposes real-time weather, forecast,
and air-quality data as tools for LLM agents like Claude. Built on the
[OpenWeather API](https://openweathermap.org/api).

## What is MCP?

MCP is Anthropic's open protocol for connecting LLMs to external tools and data
sources through a standard client-server interface. This server exposes 4 tools
that Claude (or any MCP client) can call during a conversation.

## Tools

| Tool | Description |
|---|---|
| `get_current_weather` | Current conditions for a location |
| `get_weather_forecast` | 1-5 day forecast |
| `get_air_quality` | AQI + pollutant breakdown |
| `compare_weather` | Side-by-side comparison across up to 5 cities |

## Architecture

```
server.py          MCP tool definitions — thin, delegates everything
weather_client.py  Async API client — geocoding, caching, retries
models.py          Pydantic schemas for validated, typed responses
exceptions.py      Typed exceptions instead of ad-hoc error dicts
config.py          Environment/settings management
```

The design goal: `weather_client.py` is fully unit-testable without an MCP
server or a live API key (see `tests/`), because the tool layer never touches
HTTP directly.

Notably, all API calls use `httpx.AsyncClient` rather than the synchronous
`requests` library — a common mistake in `async def` functions is using a
blocking HTTP client, which stalls the event loop for every other concurrent
request the server is handling.

## Setup

Uses [uv](https://docs.astral.sh/uv/) for dependency management.

```bash
git clone https://github.com/AsifMarwat/weather-mcp-pro.git
cd weather-mcp-pro
uv venv
uv pip install -r requirements.txt
cp .env.example .env  # add your OpenWeather API key
```

Get a free API key at [openweathermap.org/api](https://openweathermap.org/api).

## Run

```bash
uv run server.py
```

## Use with Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "weather-mcp-pro": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/weather-mcp-pro", "server.py"]
    }
  }
}
```

## Example

> "What's the weather like in Peshawar right now, and how does it compare to Lahore?"

Claude calls `compare_weather(["Peshawar", "Lahore"])` and returns a natural-language
summary built from the structured response.

## Tests

```bash
uv run pytest tests/ -v
```

## License

MIT