Content
# Hermes Weather Agent
**A standalone Weather MCP server and local no-AI UI powered by rustwx and WxStore.**
Hermes Weather Agent gives Hermes Agent, Claude, and any MCP-speaking client direct access to [`rustwx`](https://github.com/FahrenheitResearch/rustwx), a pure-Rust weather workspace, and [`wxstore`](https://github.com/FahrenheitResearch/wxstore), the MIT temporal store for 2-D and 3-D weather data. It is meant to be a general weather engine for agents: model maps, satellite imagery, radar products, meteograms, soundings, cross sections, latest-run discovery, local cache management, temporal-store queries, and severe-weather research tools from one server.
The compute and rendering live in `rustwx`. PNG output goes through the pure-Rust `rustwx-render` contour engine: no matplotlib for maps, no ANSI rendering, and no Python in the hot path. WRF NetCDF4 reads use `netcrust` (pure-Rust, feature-gated) so **no `netcdf.dll` runtime is required for the standard agent workflows.**
Hermes defaults RustWx renders to the current fast operational plot style by setting `RUSTWX_PLOT_STYLE=operational_fast` when no explicit style is configured. The Rust CLI also accepts `operational-fast`; use `HERMES_RUSTWX_PLOT_STYLE` or `RUSTWX_PLOT_STYLE` to override it.
## Why this matters
* **One MCP server for weather work.** Agents can request maps, satellite, radar, meteograms, soundings, cross sections, cache status, and background jobs without a custom web app.
* **A no-AI UI for people.** `weather-ui` opens RustWx Studio: browse models/domains/products, render operational maps, and sample point forecasts from the same released `rustwx` package APIs.
* **Latest data by default.** HRRR requests resolve against advertised forecast-hour availability; longer-range HRRR requests use the newest synoptic cycle with the requested hours.
* **Efficient local data use.** rustwx uses `.idx` byte-range fetches where possible, and Hermes exposes data-pack guidance so users can choose how much disk to reserve.
* **Temporal stores for shared weather data.** Hermes can query a running WxStore service, sample WXA grids and WXP pressure-profile stores, search object lanes, and materialize RustWx grids into durable WxStore WXA caches so repeated plotting and point sampling stay fast.
* **Live product discovery.** Product support is read from the installed `rustwx` wheel so the agent can pick slugs the active model actually advertises; optional workspace binaries expose deeper catalog metadata for local development.
* **rustwx 0.5 model compatibility.** Hermes now understands the broadened rustwx model set: HRRR/HRRR-AK, GFS/GDAS/GEFS/HGEFS, AIGFS/AIGEFS, ECMWF Open Data, AIFS/Earth2, RAP, NAM, HIRESW/HREF/SREF, RTMA/URMA, NBM, RRFS-A/RRFS-Public/REFS/RRFS-FireWx, and WRF/GDEX-style local workflows.
* **Composite and grid-plot vocabulary.** Agents can ask for built-in fill-plus-isopleth recipes, contour labels, ensemble member/stat selectors, and schema-stable grid-overlay requests such as value grids, EBS-style scalar grids, and hodograph glyph grids. Generic custom grid overlays are reserved in the schema and return a clear rustwx error until the generic renderer lands.
* **Fast regular renders by default.** Hermes keeps direct and light-derived non-ECAPE products in one shared RustWx pass so ordinary HRRR plot packs avoid repeated decode work, while heavy ECAPE, generic, and windowed requests still use guarded chunking when needed. Set `chunk_size` for explicit chunk control or `chunk_large_requests=false` / `chunk_size=0` to force one pass.
* **Advanced severe-weather research when needed.** ECAPE maps, profile probes, profile sweeps, ratio maps, and severe panels are available as regular tools, not as a separate research-only app.
## What an agent can do with this
```
"Render latest HRRR 2 m temperature and 10 m wind over Los Angeles."
"Show me the latest GOES-West GeoColor image with GLM overlay for southern California."
"Make a point meteogram for Redding for the next 18 hours."
"Render KTLX base reflectivity and dual-pol products."
"Cross-section theta-e from Amarillo to Chicago at f06 using the HRRR VolumeStore."
"What does the latest CONUS QPF look like at f24?"
"Export latest HRRR temperature, wind, and CAPE grids into WxStore."
"Materialize latest HRRR severe grids into WxStore, then render f000-f002 operational maps from the WXA cache."
"Sample the WxStore temporal sounding lane near Norman and include severe diagnostics."
"Render MLECAPE and 0-3 km SRH over the southern plains for the latest HRRR."
"Render HRRR DCAPE over Oklahoma City."
"Probe the ECAPE profile at Norman, OK at the latest f01."
"Build a 7-day dataset of MLECAPE / SRH 0-3 / STP renders for southern-plains."
"What's currently in the cache, and what would a 400 GB eviction free?"
```
## Advanced Research Mode
The general weather tools are the main surface area. On top of that, Hermes Weather Agent includes ECAPE and severe-weather research tools for deeper work:
* full-parcel ECAPE and DCAPE maps at HRRR-grid scale
* per-profile ECAPE diagnostics from the Rust solver
* random/target/stress profile sweeps
* severe-weather panels and ECAPE/CAPE ratio products
* multi-day render/probe datasets for verification workflows
The ECAPE path is strong for exploratory and product-triage research, not yet calibrated forecast skill. Calibration is downstream of the verification work these tools enable.
## Install
```bash
pip install -U rustwx hermes-weather-agent
weather-mcp --doctor
weather-ui
```
That's it for every map-rendering tool — the rustwx PyPI wheel ships the `rustwx-agent-v1` Python API used by this plugin (no Rust toolchain, no separate binaries, no `netcdf.dll`). `rustwx>=0.5.10` is recommended for the current public release.
`weather-mcp --doctor` should report `rustwx_module_available: true`, `agent_api: rustwx-agent-v1`, `plot_style: operational_fast`, and a nonzero `domain_count`.
`weather-ui` starts RustWx Studio at `http://127.0.0.1:8765/`. It uses the installed package APIs directly, so non-agent users can render maps and sample point forecasts without an MCP client.
### Optional specialty tools
A small set of tools sit *outside* the agent-v1 contract today and need rustwx workspace binaries to be built locally:
- `wx_sounding` (skew-T renderer)
- `wx_cross_section` / `wx_volume_cross_section` (HRRR pressure VolumeStore renderer; all non-smoke wxsection styles)
- `wx_radar` (NEXRAD Level-II renderer)
- `wx_native_dataset_plan` / `wx_native_dataset_run` (Rust-native HRRR/GOES/MRMS/Level-II training-data plans and shards)
- `wx_native_obs_preview` (quicklook PNGs from local GOES, MRMS, or Level-II files)
- `wx_goes_native_sequence` (native-grid GOES crops, time-window sequences, and GIF loops)
- `wx_ecape_profile` (single-point ECAPE probe)
- `wx_ecape_grid` (full-grid ECAPE swath research)
- `wx_wxstore_grid_export` (RustWx to WxStore dense-grid manifest export)
- `wx_wxstore_grid_import` (WxStore CLI import of one or more exported manifests)
- `wx_wxstore_grid_materialize` (one-call RustWx export plus WxStore WXA import)
- `wx_wxstore_grid_plot` (fast static PNG rendering from cached WXA grids)
If you want those too:
```bash
git clone https://github.com/FahrenheitResearch/rustwx
cd rustwx
cargo build -p rustwx-cli --release \
--bin sounding_plot \
--bin hrrr_pressure_volume_store \
--bin volume_store_cross_section_render \
--bin radar_export \
--bin native_dataset_plan \
--bin native_dataset_runner \
--bin native_obs_preview \
--bin goes_native_sequence \
--bin hrrr_ecape_profile_probe \
--bin hrrr_ecape_grid_research \
--bin rustwx_grid_export \
--bin wxstore_wxa_showcase
export HERMES_RUSTWX_BIN_DIR="$(pwd)/target/release"
```
To import exported grids into WxStore, also build the WxStore CLI and point Hermes at it:
```bash
git clone https://github.com/FahrenheitResearch/wxstore
cd wxstore
cargo build --release
export HERMES_WXSTORE_BIN_DIR="$(pwd)/target/release"
export HERMES_WXSTORE_URL="http://127.0.0.1:8897"
```
These will fold into the agent-v1 contract or service APIs as they stabilize; until then, the corresponding MCP tools degrade with a clear "build the binary" or "service unavailable" error rather than blocking the rest of the plugin.
## Configure
```yaml
# Hermes Agent — ~/.hermes/config.yaml
mcp_servers:
weather:
command: weather-mcp
env:
HERMES_RUSTWX_BIN_DIR: /path/to/rustwx/target/release
HERMES_WXSTORE_BIN_DIR: /path/to/wxstore/target/release
HERMES_WXSTORE_URL: http://127.0.0.1:8897
HERMES_RUSTWX_PLOT_STYLE: operational_fast
HERMES_CACHE_DIR: /path/to/weather-cache # default: ./cache/rustwx
HERMES_OUT_DIR: /path/to/weather-outputs # default: ./outputs
```
```json
// Claude Desktop / generic MCP — claude_desktop_config.json
{
"mcpServers": {
"weather": {
"command": "weather-mcp",
"env": { "HERMES_RUSTWX_BIN_DIR": "/path/to/rustwx/target/release" }
}
}
}
```
## CLI
```bash
weather-mcp --list # every MCP tool with one-line descriptions
weather-mcp --doctor # binary discovery + product catalog state
weather-mcp --test # smoke-test render
weather-ui # local browser UI for RustWx maps and point forecasts
```
## Tools (49 total)
### Discovery
| Tool | Purpose |
|---|---|
| `wx_models` | Available models, sources, products, forecast horizons |
| `wx_products` | Product slugs advertised by the installed `rustwx` wheel, filterable by kind/model/status/search |
| `wx_recipes` | Compact recipe summary (live with fallback mirror) |
| `wx_regions` | rustwx region presets |
| `wx_doctor` | Local install diagnostics |
| `wx_latest` | Resolve the latest available run for a model |
| `wx_data_packs` | HRRR-first local storage tiers: what works without more downloads at 1/5/10/50 GB style budgets |
Hermes is HRRR-first for local operational use. Tool defaults use `run="latest"` and resolve against advertised forecast-hour availability; requests for f019-f048 use the newest HRRR synoptic cycle that actually has those hours. Local data-pack tiers are cache/retention guidance: rustwx uses `.idx` byte-range fetches wherever the requested fields can be safely subset, while larger tiers simply retain more warmed hours, routes, and artifacts.
### Direct & derived rendering
| Tool | Purpose |
|---|---|
| `wx_fetch` | Fetch model GRIB2 data via rustwx with idx-byte-range selective download by default |
| `wx_render_recipe` | Render any combination of direct / derived / windowed / heavy recipes (auto-routes to the right binary) |
| `wx_composite` | Built-in composite/isopleth recipe helper plus schema-stable custom composite/grid-overlay requests |
| `wx_cape` | SBCAPE / MLCAPE / MUCAPE shortcut |
| `wx_ecape` | First-class ECAPE map (sbecape / mlecape / muecape) |
| `wx_srh` | 0-1 km or 0-3 km SRH |
| `wx_shear` | 0-1 km or 0-6 km bulk shear |
| `wx_stp` | Fixed-layer Significant Tornado Parameter |
| `wx_windowed` | Time-window products: full HRRR QPF/UH/surface-extrema family, plus cross-model `qpf_total` for validated v0.5 indexed-GRIB models |
| `wx_severe_panel` | Multi-product severe + ECAPE plate from one shared heavy thermo load |
### ECAPE specialists
| Tool | Purpose |
|---|---|
| `wx_ecape_profile` | Per-profile ECAPE diagnostics at a (lat, lon) — sub-millisecond Rust solver |
| `wx_ecape_grid` | Full-grid ECAPE research over a swath (background) |
| `wx_ecape_ratio_map` | MLECAPE filled + ECAPE/CAPE ratio contours w/ magnitude mask |
### Vertical / observations
| Tool | Purpose |
|---|---|
| `wx_cross_section` | Compatibility alias for HRRR pressure VolumeStore cross sections |
| `wx_volume_cross_section` | HRRR pressure VolumeStore cross sections; builds a short-lived 1-3 hour local store and renders PNG/WebP for all non-smoke wxsection styles |
| `wx_satellite` | Latest GOES satellite imagery via `rustwx.render_goes_satellite_json`; supports GeoColor, GLM overlay, RGB composites, and ABI Bands 1-16 |
| `wx_meteogram` | Point forecast time series via `rustwx.sample_point_timeseries_json`, or a warmed store when `store_id` is supplied |
| `wx_meteogram_warm_store` | Warm a point-timeseries grid store for repeated meteogram sampling |
| `wx_radar` | Native rustwx NEXRAD Level-II rendering via `radar_export`: base, dual-pol, SRV, VIL, echo tops, and feature JSON |
| `wx_sounding` | Skew-T at (lat, lon) rendered by rustwx's native `sounding_plot` binary; supports `sample_method="box-mean"` with `box_radius_km` |
| `wx_native_obs_preview` | Quicklook PNG from a local GOES, MRMS, or Level-II file before it becomes a training shard; Level-II velocity supports rustwx dealiasing |
| `wx_goes_native_sequence` | Fast GOES ABI image/loop generator for arbitrary lat/lon boxes, full disk, CONUS, or mesoscale sectors; can return PNG frames and an animated GIF |
### WxStore temporal stores
| Tool | Purpose |
|---|---|
| `wx_wxstore_status` | Check WxStore service health and local binary discovery |
| `wx_wxstore_catalog` | Query WxStore status, model/product/variable catalogs, latest runs, observation sources, satellite/radar layers, and vertical-render status |
| `wx_wxstore_forecast` | Sample WxStore WXA spatial lanes as Open-Meteo-style point forecasts |
| `wx_wxstore_sample` | Sample one WxStore grid variable at a lat/lon or named location |
| `wx_wxstore_temporal_sounding` | Query WxStore WXP temporal pressure-profile lanes, optionally with diagnostics |
| `wx_wxstore_objects` | Search WxStore observation, model, static-plot, evidence, satellite, radar, and source objects |
| `wx_wxstore_mesoanalysis` | Query WxStore mesoanalysis innovation status, targeted station/source checks, and watchlists |
| `wx_wxstore_grid_export` | Export RustWx direct, derived, or windowed grids into WxStore-importable WXA manifests |
| `wx_wxstore_grid_import` | Import one or more exported manifests into a WxStore spatial root and optionally publish latest |
| `wx_wxstore_grid_materialize` | Export RustWx grids and import them into a durable WXA spatial cache in one call |
| `wx_wxstore_grid_plot` | Render operational-fast static PNGs directly from cached WXA grids |
### Research mode
| Tool | Purpose |
|---|---|
| `wx_research_profile_sweep` | Multi-point ECAPE sweep across (point × date × cycle × fhour). Modes: `targets` / `random` / `stress`. Aggregated CSV with timing breakdown |
| `wx_build_dataset` | Multi-day batch renders or profile probes (background) |
| `wx_native_dataset_plan` | Write a selectable HRRR/GOES/MRMS/Level-II training-data plan |
| `wx_native_dataset_run` | Fetch/materialize a native training-data plan into shards |
### Cache & jobs
| Tool | Purpose |
|---|---|
| `wx_cache_status` | Disk usage + top consumers + per-subdir totals |
| `wx_cache_evict` | LRU eviction to bring cache below `target_gb` (dry-run by default) |
| `wx_job_status` / `wx_job_list` / `wx_job_cancel` | Background-job control |
## Showcase gallery
The repo ships a one-shot script that exercises every tool against a single canonical run, captures per-call timing, and emits a self-contained HTML gallery:
```bash
python examples/showcase_full.py # ~3 min with warm cache, ~5 min cold
python examples/showcase_html.py # builds outputs/showcase/index.html
```
The showcase includes HRRR VolumeStore cross sections, the GOES18 product set, direct point meteograms, warmed point-timeseries store sampling, and native rustwx radar export. Open `outputs/showcase/index.html` after running.
Top wall-time consumers from the canonical run:
```
42.7 s HRRR derived — 44 recipes / one shared decode 72 PNGs
41.3 s HRRR severe panel (heavy_panel_hour) 24 PNGs
35.1 s ECAPE/CAPE ratio display (background) 6 PNGs
8.0 s mini research dataset (1 cycle × 2 recipes)
7.9 s HRRR windowed — 8 QPF/UH products 6 PNGs
6.6 s HRRR direct — 52 recipes / one shared decode 72 PNGs
6.6 s ECAPE grid research (background)
5.9 s stress profile sweep (10 curated points)
5.1 s GFS derived (sbcape/mucape/lapse) 6 PNGs
4.7 s ×5 cross sections (4 routes + 1 city pair)
```
The HRRR direct + derived passes each render dozens of products from one shared thermodynamic decode — that's where the per-product cost approaches zero. A focused HRRR CONUS benchmark with the default smart chunk policy produced 81 regular non-ECAPE PNGs (52 direct + 29 light-derived) in 27.27 s warm-cache for one hour, and 162 PNGs in 56.27 s warm-cache for two hours.
## Programmatic use (without an LLM)
Every tool is also a plain Python function:
```python
from hermes_weather.rustwx import discover
from hermes_weather.tools import (
render, ecape, volume_cross_section,
satellite, meteogram, radar, catalog, wxstore,
)
env = discover()
# Single first-class ECAPE map
out = render.ecape(env, parcel="ml", region="southern-plains",
run_str="latest", forecast_hour=0)
print(out["pngs"])
# Per-profile ECAPE in <1ms (Rust kernel)
prof = ecape.profile(env, location="Norman, OK",
run_str="latest", forecast_hour=1,
include_input_column=True)
print(prof["diagnostics"]["parcels"][1]["ratio_ecape_to_undiluted_cape"])
# HRRR VolumeStore cross sections: temporary 1-hour SoCal cube,
# all non-smoke wxsection styles, PNG + WebP outputs.
fast_xs = volume_cross_section.volume_cross_section(
env, products=["all"], route="socal-coast-desert",
run_str="latest", forecast_hour=0,
)
# GOES satellite set, short point meteogram, and native radar export.
sat = satellite.satellite(env, products=satellite.DEFAULT_PRODUCTS)
met = meteogram.meteogram(env, location=(34.0522, -118.2437),
forecast_hour_start=0, forecast_hour_end=3)
rad = radar.radar(env, site="KTLX", products="all")
# Discover what every recipe is and where it works
products = catalog.products(env, kind="derived", search="ecape")
for p in products["products"]:
supported_models = [s["model"] for s in p["support"] if s["status"] == "supported"]
print(f"{p['slug']:35s} {p['maturity']:14s} {supported_models}")
# Query WxStore if a service is running
store = wxstore.catalog(env, endpoint="latest", model="hrrr", domain="conus")
print(store)
# Cache-first WXA workflow: pay the GRIB -> grid cost once, then plot quickly.
mat = wxstore.grid_materialize(
env,
products=["vpd_2m", "dewpoint_depression_2m", "heat_index_2m", "stp_fixed"],
forecast_hours="0-2",
region="conus",
jobs=4,
)
plots = wxstore.grid_plot(env, products=["stp_fixed"], forecast_hours="0-2")
print(mat["spatial_root"], plots["png_count"])
```
## Speed reality check (ECAPE-RS validation paper, April 2026)
| Operation | Python (`ecape-parcel` + MetPy) | Rust (`rustwx-calc`) | Speedup |
|---|---|---|---|
| ECAPE per HRRR profile (one parcel/config) | 2.8–6.1 s | 0.45–0.65 ms | **5,600–13,000×** |
| ECAPE full-grid (272,955 HRRR cells / forecast hour) | impractical | 17.6–18.4 s | — |
Per-profile ECAPE is essentially free; full-grid is the heavy one. Heavy tools (`wx_ecape_grid`, `wx_ecape_ratio_map` for CONUS, `wx_research_profile_sweep` over many cycles) run as background jobs. Profile-sweep results separate `raw_fetch_s` / `profile_extract_s` / `parcel_solver_s` / `render_s` so you can attribute time honestly.
## License
MIT.
## Acknowledgements
Built on top of [`rustwx`](https://github.com/FahrenheitResearch/rustwx) (Rust meteorology workspace, Fahrenheit Research), [`wxstore`](https://github.com/FahrenheitResearch/wxstore) (MIT temporal stores for weather data), and the public `ecape-parcel` reference implementation. Validation methodology described in *Validation and Acceleration of an ecape-parcel-Compatible Solver for HRRR-Scale Entraining-CAPE Diagnostics*, ECAPE-RS Project, April 2026.
