nws-heatrisk-mcp — Model Context Protocol server for the NWS public API and the WPC HeatRisk productA 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).
| 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).
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:
nws_heatrisk(lat, lon)).Environmental block of an
observation, with full provenance.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.
# Pattern: "<app-name> (<contact email or URL>)"
export NWS_USER_AGENT="epihack-az-2026-sentinel (contact@example.org)"
A .env.example template is included; copy to .env and source it.
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:
# 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.
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.
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 |
uv if you don’t have it.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).NWS_USER_AGENT to a real value (your app + a real contact).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
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.
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.
Status of the live check against production endpoints, run from the EpiHack VM on 2026-05-21.
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.
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 pytestand 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 allowlistedcurlprobes 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-runuv run pytest -qand the probe inexamples/to record live values.
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.
NWS_HEATRISK_URL is
pointed at the current product.MIT, alongside the rest of epihack-2026.