mag-hrn-mcp — Model Context Protocol server for the MAG Heat Relief NetworkA Model Context Protocol server that exposes the Maricopa Association of Governments Heat Relief Network — ~200+ cooling, hydration, respite, and donation-drop-off sites across the Phoenix metro that operate each year from May 1 through September 30 — 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) — the
mag_search_centers(lat, lon, radius=2km, open_now=true,
pets_ok=false) call in step 7.
Mock-by-default. This server ships with a small canned dataset of 12 realistic Phoenix-metro sites (Burton Barr Central Library, Andre House of Hospitality, Mesa Main Library, Tempe Public Library, etc.) so the rest of the EpiHack stack can develop against it without hitting MAG infrastructure. Set
MAG_HRN_FEATURE_SERVICE_URLin the environment to flip to the real MAG ArcGIS service (see Pointing at the real ArcGIS service below).
| MCP tool | What it returns |
|---|---|
mag_search_centers |
Centers within radius_km of (lat, lon), filtered by open_now, pets_ok, and services. Each row: {id, name, address, city, postal_code, lat, lon, services, hours_today, pets_ok, distance_km, kg_node_id}. |
mag_center_detail |
Full record for a center including hours-by-day, operator, notes, and a placeholder kg_node_id. |
mag_list_open_now |
Snapshot of every center currently open (optionally pinned to a specific timestamp). |
mag_supply_status |
MOCK supply / occupancy heads-up: {water_status, seats_available, last_updated_iso, source}. See Heat-Q2. |
mag_search_by_text |
Free-text lookup (“library”, “church”, “donation”) with optional [lat, lon] distance-sort hint. |
Plus two MCP resources:
mag://service-types — reference text for cooling | hydration | respite | donation (the tight 4-value vocabulary the client normalizes onto).mag://operating-window — the May 1 – September 30 season convention and the off-season-returns-empty contract.The Heat Relief Network is the only network in the country, at this scale, that has stood up regional cooling/hydration coordination across municipal boundaries every summer for over a decade. Wrapping it as an MCP server lets an agent:
mag_search_centers(lat, lon)), bounded to the operating season.mag_search_centers → 211-az-mcp.transport_to_cooling_center).mag_supply_status) so when MAG
ships a real-time feed the rest of the stack already knows the
shape — that’s Heat-Q2 in plan/01.| Value | Meaning |
|---|---|
cooling |
Indoor air-conditioned cooling center. |
hydration |
Walk-up water-bottle distribution (may be outdoors). |
respite |
Cooling center where uninterrupted rest is permitted. |
donation |
Drop-off site for public donations (not a relief site for those in need). |
Real MAG ArcGIS rows arrive with various labels (LocationType,
Type, CenterType, etc.); the client’s _normalize_services maps
them onto these four values. One center can carry more than one type
(a library is often cooling + hydration).
The HRN runs May 1 through September 30 each year. Outside this
window every tool returns an empty centers list and off_season:
true. The 2026 launch date is
official.
Phoenix doesn’t observe DST, so all open-now math runs in MST (UTC-7).
The canned 12-site dataset covers Phoenix, Mesa, Tempe, Glendale, Scottsdale, Chandler, Surprise, and Goodyear — a reasonable cross- section of the real network’s geography. Site names, addresses, and coordinates are based on real, well-known locations so the multi-MCP join in Scenario C feels right; operating hours and supply notes are plausible but synthetic — defer to hrn.azmag.gov for authoritative data.
Public probing of geo.azmag.gov (May 2026) shows the HRN’s ArcGIS
service at:
https://geo.azmag.gov/arcgis/rest/services/maps/Heat_Relief_Network/MapServer
with at least a “Respite Center” layer at ID 1; per-season layer
indexes for cooling, hydration, and donation drop-off sit alongside.
A FeatureServer flavour of the same service may also exist (MAG has
historically published both). The exact URL drifts every season, so
the client reads it from MAG_HRN_FEATURE_SERVICE_URL:
export MAG_HRN_FEATURE_SERVICE_URL=https://geo.azmag.gov/arcgis/rest/services/maps/Heat_Relief_Network/MapServer
export MAG_HRN_FEATURE_LAYER=all # walks every layer the service advertises
# Optional bearer token if a partner-only feed eventually requires one.
# export MAG_HRN_API_TOKEN=...
The client’s _ArcGISBackend:
<service_url>?f=json to enumerate layers when MAG_HRN_FEATURE_LAYER=all.GET <service_url>/<layer>/query?where=1=1&outFields=*&outSR=4326&f=json.Name/SiteName/FACILITY, Address/ADDRESS1/Street,
LocationType/Type/CenterType, etc.) onto the canonical row
shape the MCP tools return.If MAG renames attributes mid-season, extend the
_NAME_FIELDS / _ADDR_FIELDS / _TYPE_FIELDS aliases in
client.py.
A .env.example template is included; copy to .env and source it.
mag_supply_status mock — Heat-Q2mag_supply_status is currently mock-only. MAG does not yet
publish a real-time occupancy/supply feed, and that gap is the entire
subject of Heat-Q2 (Real-time resource sharing between cooling
centers). The MCP tool exists
now so the rest of the EpiHack stack can develop against the eventual
feed’s shape:
{
"center_id": "mag.hrn.mock.0002",
"found": true,
"name": "Andre House of Hospitality",
"water_status": "low", // ok | low | out
"seats_available": 7, // int or null
"last_updated_iso": "2026-07-18T14:05:00",
"source": "mock", // flips to "feed" once a real feed ships
"note": "MOCK feed. MAG does not yet publish a real-time supply feed; see plan/01-parameter-mapping.html Heat-Q2."
}
The mock derives its values deterministically from the center ID so multiple calls in the same session return stable values for a demo.
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).MAG_HRN_FEATURE_SERVICE_URL empty to run in mock mode, or
point it at the active MAG ArcGIS service for live data.cd mcp/mag-hrn-mcp
uv sync
uv run mag-hrn-mcp # stdio (default)
MCP_TRANSPORT=streamable-http uv run mag-hrn-mcp # HTTP
cd mcp/mag-hrn-mcp
uv run pytest
The test suite is fully offline. It exercises the haversine math, the
open-now / pets-ok / services filters, the free-text search, the
off-season-returns-empty contract, and the mock supply-status response
shape (source: "mock").
MIT, alongside the rest of epihack-2026.