# gb-climate-mcp

[![test](https://github.com/nawazxz/gb-climate-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/nawazxz/gb-climate-mcp/actions/workflows/test.yml)

An [MCP](https://modelcontextprotocol.io) server that gives Claude (or any MCP client) 35 years of daily weather for Gilgit-Baltistan, Pakistan, and a live flash-flood screening outlook for its valleys.

Ask things like:

> Is the coming week risky for flash floods in Hunza?
>
> How has snowfall changed at Skardu since 1990?
>
> How unusual was the rain in Gilgit on 26 August 2022?

## Why this exists

Flash floods and glacial outbursts hit Gilgit-Baltistan every summer, and many valleys have little or no local early warning. Public weather data for the region also has a trap in it: at four of the five stations the ERA5 reanalysis jumps by 5 to 6.5 °C on average (up to 10 °C in winter) between December 2016 and January 2017, an artefact of a change in how the model assimilates data. Anyone who pulls the raw series and fits a line finds about **+1.4 °C of warming per decade**. After correcting the step, the five-station average is about **+0.08 °C per decade**.

This server bundles the corrected record and is written to stop a model from repeating that kind of mistake. Trend tools warn when a range crosses the break, and the caveats are exposed as a resource the model is told to read.

## Tools

| Tool | What it does |
|---|---|
| `list_stations` | Five stations from 1,250 m (Chilas) to 4,693 m (Khunjerab), coverage and variables |
| `get_daily_weather` | Daily values for one station, up to a year per call |
| `climate_trend` | Yearly totals or means plus the linear trend per decade |
| `compare_stations` | One variable across all stations, ordered by elevation |
| `rain_thresholds` | What counts as a heavy, extreme or once-in-years rain day at a station |
| `flood_risk_outlook` | Live 1 to 16 day outlook scored against the station's own history |

Resource: `gb://methodology` covers the source, the correction and what it cannot fix.

All tools are read-only. Only `flood_risk_outlook` touches the network (the free [Open-Meteo](https://open-meteo.com) forecast API, no key). Everything else works offline.

## How the flood outlook works

Each forecast day is scored on three drivers, all relative to that valley's own 35-year record:

1. **Daily rain** against the station's 90th, 95th, 99th and 99.9th percentiles
2. **Peak hourly rain**, the cloudburst signal a daily total hides
3. **Heat-driven melt**: a day hotter than 95% of that station's summer days, scored higher after recent snow

The heat threshold is learned per station, not fixed. A hot summer day is about 36 °C in Gilgit but about 6 °C at Khunjerab, and a single fixed cutoff (the first version of this used 32 °C) fires constantly in the low valleys and never at the pass.

## Install

Requires Python 3.10+.

**Claude Code**

```bash
claude mcp add gb-climate -- uvx --from git+https://github.com/nawazxz/gb-climate-mcp gb-climate-mcp
```

**Claude Desktop** (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "gb-climate": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/nawazxz/gb-climate-mcp", "gb-climate-mcp"]
    }
  }
}
```

**From source**

```bash
git clone https://github.com/nawazxz/gb-climate-mcp && cd gb-climate-mcp
python -m venv .venv && .venv/bin/pip install -e '.[dev]'
.venv/bin/pytest
```

## Data

ERA5 reanalysis (ECMWF / Copernicus) via the Open-Meteo Historical Weather API, 1990 to 2024, 63,920 station-days. Built from the raw series in [gilgit-baltistan-era5-weather](https://github.com/nawazxz/gilgit-baltistan-era5-weather) by `scripts/build_data.py`. Pre-2017 rows are shifted onto the post-2017 baseline per station, variable and calendar month; the factors are in `src/gb_climate_mcp/data/corrections.json`.

| Station | Elevation | Mean temp trend 1990-2024 (°C/decade) |
|---|---|---|
| Chilas | 1,250 m | +0.11 |
| Gilgit | 1,500 m | +0.16 |
| Skardu | 2,228 m | +0.02 |
| Hunza | 2,438 m | +0.04 |
| Khunjerab | 4,693 m | +0.05 |

## Limitations

These matter more than the features, so they are spelled out:

- **Precipitation is for a 25 km grid cell, not the valley floor.** ERA5 gives Gilgit about 1,430 mm of rain a year. The Gilgit gauge records about 130 mm, because the town sits in a rain shadow while the grid cell includes the wet mountains around it. The server uses rain only in relative terms (percentiles, anomalies, trends), and the tool descriptions tell the model to do the same.
- **The break correction absorbs real change.** Matching monthly means across 2017 removes the artificial step and also any genuine difference between the two periods, so trends across 2017 are conservative.
- **The flood outlook is not validated.** It has not been tested against recorded flood events yet, the hourly bands (4, 8, 15 mm/h) are hand-set, and the live forecast model is not on exactly the same scale as ERA5. Treat it as a screening signal. Official warnings come from PMD and GBDMA.

## Licence

Code: MIT. Data: CC BY 4.0, contains modified Copernicus Climate Change Service information (see `DATA_LICENSE`).