Skip to content

nws-heatrisk-mcp

Source

Server lives at mcp/nws-heatrisk-mcp/. The content below is included verbatim from its README.md.


title: NWS HeatRisk MCP server

nws-heatrisk-mcp — Model Context Protocol server for the NWS public API and the WPC HeatRisk product

A Model Context Protocol server that exposes the U.S. National Weather Service public API (api.weather.gov) and the WPC HeatRisk gridded product as a set of tools an LLM (Claude Desktop, Claude Code, Claude API agents, or any other MCP client) can call.

Built for the EpiHack Arizona 2026 Heat focus group. Powers the Heat-vertical scenarios in plan 04, in particular Scenario C (unsheltered heat check-in on a Magenta-HeatRisk day).

What it does

MCP tool Backed by
nws_heatrisk WPC HeatRisk daily gridded product
nws_heatrisk_week WPC HeatRisk (7-day outlook)
nws_forecast GET /points/{lat},{lon} then the returned forecast / forecastHourly URL
nws_current_conditions GET /points/{lat},{lon}/stations then GET /stations/{id}/observations/latest
nws_heat_index client-side: NWS Rothfusz regression with humidity adjustments
nws_active_heat_alerts GET /alerts/active?area=...&event=... for each heat event name
nws_alert_zones_for_point GET /points/{lat},{lon} (extracts the zone IDs)

Plus two MCP resources: nws://heatrisk-categories (Green / Yellow / Orange / Red / Magenta with HHS-aligned heat-health descriptions) and nws://api-base-url (the active NWS_BASE_URL and User-Agent).

Why this matters for EpiHack

The NWS public API is the authoritative live source for U.S. weather data, and HeatRisk is the only nationally-published forecast that combines forecast temperature, anomaly from local climatology, and health-impact thresholds into a single 0-4 category an LLM (or a clinician) can act on. Exposing both as an MCP server lets an agent:

  • Answer "is today dangerous heat for this person?" with a single call (nws_heatrisk(lat, lon)).
  • Cross-check the WPC forecast against any open NWS warnings for the exact zone the user is standing in.
  • Compute the heat index live from the nearest observation station without leaving the conversation.
  • Drop the result into the DuckLake knowledge graph as the Environmental block of an observation, with full provenance.

Authentication

None. The NWS public API has no token. It does require a descriptive User-Agent header that identifies the application and provides a contact (email or URL). Requests without one are rejected. The server refuses to start without NWS_USER_AGENT set, with a clear error.

```bash

Pattern: " ()"

export NWS_USER_AGENT="epihack-az-2026-sentinel (contact@example.org)" ```

A .env.example template is included; copy to .env and source it.

HeatRisk URL drift caveat

NWS HeatRisk is an experimental product whose machine-readable endpoint has moved more than once as the WPC has iterated on its hosting. The client ships with the best-known URL at build time, but makes it env-overridable:

```bash

Override if the default 404s or returns HTML rather than JSON.

export NWS_HEATRISK_URL=https://www.wpc.ncep.noaa.gov/heatrisk/data/heatrisk.json ```

The HeatRisk feed parser accepts a few common shapes (flat list of daily dicts, GeoJSON FeatureCollection, NWS-style properties.values). If your deployment encounters a new shape, extend _iter_records / extract_daily in heatrisk.py — those are the only places that need to know the wire format.

Endpoint overrides

Every api.weather.gov path is overridable via env, so the deployed server can be corrected without a code release if NWS reorganizes:

NWS_PATH_POINTS (default /points/{lat},{lon}) NWS_PATH_ALERTS_ACTIVE (default /alerts/active) NWS_PATH_STATIONS_FOR_POINT (default /points/{lat},{lon}/stations) NWS_PATH_STATION_OBSERVATIONS (default /stations/{station_id}/observations/latest) NWS_PATH_ZONE (default /zones/{zone_type}/{zone_id})

Plus NWS_BASE_URL and NWS_HEATRISK_URL as above.

Heat index

nws_heat_index(temp_f, rh_percent) is pure computation, no network. Implements the standard NWS Rothfusz regression equation with the documented low-humidity (RH < 13%, 80 < T < 112) and high-humidity (RH > 85%, 80 < T < 87) adjustments. Returns the heat index in °F plus the NWS caution band (Caution / Extreme Caution / Danger / Extreme Danger).

Unit tests in tests/test_heat_index.py verify the canonical table values:

T (°F) RH (%) NWS table HI computed
80 40 80 ~80
90 70 106 ~106
100 50 119 ~119
110 40 136 ~136

Install & run

As a Claude Desktop MCP server

  1. Install uv if you don't have it.
  2. Drop the snippet in examples/claude_desktop_config.json into your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows).
  3. Replace the path with the absolute path to this directory.
  4. Set NWS_USER_AGENT to a real value (your app + a real contact).
  5. Restart Claude Desktop.

Standalone

bash cd mcp/nws-heatrisk-mcp uv sync NWS_USER_AGENT="epihack-az-2026-sentinel (you@example.org)" \ uv run nws-heatrisk-mcp # stdio (default) MCP_TRANSPORT=streamable-http uv run nws-heatrisk-mcp # HTTP

Tests

bash cd mcp/nws-heatrisk-mcp uv run pytest

The unit tests verify the heat-index regression against the canonical NWS table values and check that the client's env-driven configuration (User-Agent requirement, base URL and path overrides) behaves as documented. No live NWS connection is required.

Retry behaviour

api.weather.gov returns HTTP 503 under load. The client retries 5xx responses up to 3 times with exponential backoff (0.5s, 1s, 2s) before raising. 4xx responses are surfaced immediately — they almost always indicate a malformed request or a missing User-Agent.

Production verification (2026-05-21)

Status of the live check against production endpoints, run from the EpiHack VM on 2026-05-21.

Endpoint reachability (confirmed live)

These were probed directly with curl from the deploy host:

Endpoint Result
https://api.weather.gov/ HTTP 200 — the NWS public API base is up.
https://www.wpc.ncep.noaa.gov/heatrisk/data/heatrisk.json (historic NWS_HEATRISK_URL default) HTTP 404 — the documented HeatRisk feed has moved/changed and no longer serves at this path.

The NWS API requires a descriptive User-Agent (NWS_USER_AGENT, e.g. epihack-az-2026-sentinel (contact@example.org)); requests without one are rejected.

Tests

The suite is 17 tests (8 in tests/test_client_paths.py, 9 in tests/test_heat_index.py), matching the count documented above. They are pure-unit / offline (heat-index regression vs. the canonical NWS table, and env-driven client config) and require no network.

NOTE: in the verification environment uv sync / uv run pytest and the live client probe could not be executed (the sandbox denied all non-allowlisted command execution and the web tools). The test count and content were confirmed by source inspection, and endpoint reachability by the allowlisted curl probes above, but a green pytest run and live tool calls (current conditions / forecast / alerts / station obs for Phoenix) were not captured in this session. Re-run uv run pytest -q and the probe in examples/ to record live values.

HeatRisk feed status

The historic default feed (.../heatrisk/data/heatrisk.json) returns 404 in production — the WPC HeatRisk machine-readable product has drifted from this path again. A replacement public URL was not confirmed live in this session (web search/fetch were unavailable), so the in-code default is left unchanged and remains NWS_HEATRISK_URL-overridable. When NWS/WPC's current operational HeatRisk endpoint is identified, set NWS_HEATRISK_URL (no code release needed) and, if the wire format differs, extend _iter_records / extract_daily in heatrisk.py.

Graceful degradation (fixed in this verification): previously a 404 (or any transport error) on the HeatRisk feed propagated out of NWSClient.get_heatrisk_feed() as an httpx.HTTPStatusError, which would surface to the MCP caller as a tool crash — the README's claim that the tool returns a "no data" payload only held for a 200-with-unrecognized-JSON response, not for the 404 that actually occurs today. get_heatrisk_feed() now catches httpx.HTTPError and returns None; the existing None/empty handling in extract_daily and the nws_heatrisk / nws_heatrisk_week tools then emit the graceful Unknown-category payload with a drift note instead of raising. All seven tools therefore remain callable even while the HeatRisk feed URL is unresolved.

Caveats

  • Live tool calls (forecast, current conditions, active alerts, station observations, heat index over the wire) were not executed in this session; only static analysis + allowlisted reachability probes were possible here.
  • The HeatRisk replacement URL is unresolved; the feed tools degrade gracefully rather than returning data until NWS_HEATRISK_URL is pointed at the current product.

License

MIT, alongside the rest of epihack-2026.