whispers-mcp — Model Context Protocol server for USGS WHISPersA Model Context Protocol server that exposes the U.S. Geological Survey National Wildlife Health Center’s WHISPers — the Wildlife Health Information Sharing Partnership event reporting system — 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 Wildlife & Vector-Borne Diseases focus group.
WHISPers is the federal source-of-truth for wildlife mortality/morbidity events. It is a web-based repository of basic information on current and historic wildlife mortality (death) and/or morbidity (illness) events — bird die-offs, prairie-dog plague, hantavirus rodent surveillance, HPAI in wild waterfowl — reported by federal, state, tribal, and academic partners and curated by the USGS NWHC. Partners use it to alert each other to emerging wildlife disease activity; the public-portal subset of events is the layer this MCP wraps.
https://whispers.usgs.gov/api/ (confirmed
against the Angular frontend’s
src/environments/environment.prod.ts).Every tool name starts with whispers_.
| MCP tool | Backed by | Auth |
|---|---|---|
whispers_events_recent |
GET /api/eventsummaries/ (with public=true + date filter) |
none |
whispers_event_detail |
GET /api/eventdetails/{id}/ |
none |
whispers_events_bbox |
GET /api/eventsummaries/ + client-side bbox filter |
none |
whispers_events_by_species |
GET /api/eventsummaries/ (species substring) |
none |
whispers_events_by_diagnosis |
GET /api/eventsummaries/ (diagnosis substring) |
none |
whispers_az_recent_summary |
GET /api/eventsummaries/?administrative_level_one_name=AZ + local aggregation |
none |
Plus two MCP resources:
whispers://event-types — the WHISPers event-type enumeration
(Mortality/Morbidity, Surveillance).whispers://diagnosis-vocabulary — a representative slice of the
WHISPers diagnosis controlled vocabulary
(Avian influenza, HPAI, Yersinia pestis, Hantavirus,
West Nile virus, …). Refresh from
/api/diagnoses/?no_page=true for the authoritative full list.All read tools above are guaranteed-no-auth: the upstream
EventViewSet.get_queryset() filters anonymous callers to rows where
public=True, so the public subset of WHISPers is freely callable.
A future write-oriented tool (creating events, adding diagnoses) or
one calling non-public/admin-only viewsets — userchangerequests,
servicerequests, drafts, restricted contacts — would need a
WHISPers Gateway account. The MCP server keeps the auth boundary at
the server process, never sending credentials through the LLM.
WHISPers is exactly the kind of agency dataset the
EnrichmentAgent
needs to attach to community VBD reports: “did anyone find dead
prairie dogs near this Coconino check-in last week?” One bbox call
answers that. Scenario D in
plan/04-data-flows.md walks through
the exact ADHS dashboard query against the resulting graph nodes.
The build sandbox the MCP was authored in cannot reach
whispers.usgs.gov, and many EpiHack venues will have similarly
restrictive networks. To keep tests hermetic and demos resilient,
whispers-mcp ships with a small canned AZ-centric dataset in
src/whispers_mcp/canned.py. The
10-row dataset is modelled on real history:
Fallback behaviour:
WHISPERS_USE_MOCK |
live host reachable | result |
|---|---|---|
| unset (default) | yes | live API |
| unset (default) | no | canned dataset (silent fallback) |
1 |
— | canned dataset always |
Set WHISPERS_DISABLE_FALLBACK=1 to surface upstream errors
instead of silently degrading — useful in production where you’d
rather get paged than serve stale-looking data.
Event IDs in the canned dataset are intentionally in the 9 000 000+
range so they don’t collide with real WHISPers rows; the
public_url fields will 404 against the live UI on purpose.
uv if you don’t have it.examples/claude_desktop_config.json
into your Claude Desktop config.No credentials are required for the default tool set.
cd mcp/whispers-mcp
uv sync
uv run whispers-mcp # stdio (default)
MCP_TRANSPORT=streamable-http uv run whispers-mcp # HTTP
WHISPERS_USE_MOCK=1 uv run whispers-mcp # force canned data
cd mcp/whispers-mcp
uv run pytest
All tests are offline; they exercise the canned dataset directly via
the WhispersClient(use_mock=True) code path.
Every path is overridable via env — WHISPERS_PATH_EVENTS,
_EVENT_SUMMARIES, _EVENT_DETAILS, _EVENT_TYPES,
_EVENT_LOCATIONS, _SPECIES, _DIAGNOSES, _ADMIN_L1,
_ADMIN_L2. Set WHISPERS_BASE_URL to point at a staging deploy.
See .env.example for the full list.
MIT, alongside the rest of epihack-2026.