# Weather MCP Server

A Model Context Protocol (MCP) server that gives Claude live weather forecasts
and air quality data for any location in the world, powered by the free
[Open-Meteo](https://open-meteo.com) API (no API key required).

Built by following [Anthropic's MCP quickstart guide](https://modelcontextprotocol.io/docs/develop/build-server),
then extended to work globally instead of US-only.

## Tools

### `get_forecast(location: str)`

Returns current conditions and a 5-day forecast for the given place name.

```
get_forecast("Delhi")
```

### `get_air_quality(location: str)`

Returns current AQI and pollutant levels (PM2.5, PM10, CO, NO2, ozone) for the
given place name.

```
get_air_quality("Delhi")
```

## Setup

Requires Python 3.10+ and [`uv`](https://docs.astral.sh/uv/).

```bash
uv venv
uv add "mcp[cli]"
```

## Running the server

```bash
uv run weather.py
```

This starts the server over stdio and waits for an MCP client to connect —
it won't print anything, that's expected.

## Testing without a client

Use the official [MCP Inspector](https://github.com/modelcontextprotocol/inspector):

```bash
npx @modelcontextprotocol/inspector uv run weather.py
```

This opens a local web UI where you can call `get_forecast` and
`get_air_quality` directly and see the results.

## Using it with Claude Code

```bash
claude mcp add --transport stdio weather -- uv --directory /path/to/this/project run weather.py
```

Then just ask Claude Code about the weather anywhere in the world.

## How it works

- Place names are geocoded to latitude/longitude via Open-Meteo's geocoding API.
- Forecast and air quality data are fetched from Open-Meteo's forecast and
  air-quality endpoints.
- Results are formatted into plain text for the model to read.

## License

MIT