whispers-mcp — Model Context Protocol server for USGS WHISPers

A 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.

What WHISPers is

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.

What it does

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:

Auth boundary

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.

Why this matters for EpiHack

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.

Mock-by-default fallback

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.

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.
  3. Replace the path with the absolute path to this directory.
  4. Restart Claude Desktop.

No credentials are required for the default tool set.

Standalone

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

Tests

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.

Endpoint overrides

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.

License

MIT, alongside the rest of epihack-2026.