inaturalist-mcp — Model Context Protocol server for iNaturalistA Model Context Protocol server that wraps the iNaturalist public API 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.
Why iNaturalist? iNaturalist is the world’s largest open biodiversity-observations dataset — every record is a photo with a timestamp, GPS, and a community-verified species ID, released under permissive CC licenses. For One Health surveillance in Arizona it gives us a real-time citizen-science feed of tick, mosquito, flea, and wildlife-reservoir sightings that complements the structured-submission programs (the Walker lab’s
great-az-tick-check-mcp, AZGFD wildlife mortality, VectorSurv trap data). When a hiker photographs a tick on their dog in Cochise County, the photo shows up in iNaturalist days before the physical specimen reaches the lab.
| MCP tool | What it does |
|---|---|
inat_observations_bbox |
Public observations inside a (min_lon, min_lat, max_lon, max_lat) box, filtered by taxon + days + quality grade. |
inat_observations_near |
Convenience wrapper for (lat, lon, radius_km) — bbox + haversine sort by distance. |
inat_observations_by_taxon |
Observations of a specific taxon_id in a place_id (default: AZ, place_id=53). |
inat_taxon_lookup |
Resolve a name ("deer mouse") or numeric ID to a taxon record. |
inat_species_summary_az |
Counts by month and by AZ county-equivalent place for a taxon. |
inat_tick_observations_az |
Convenience: research-grade tick observations in AZ — the citizen-science cross-check for great-az-tick-check-mcp. |
Plus two MCP resources:
inat://tick-genera-az — AZ-relevant tick genera + species with
iNaturalist taxon IDs (quick reference; skip the lookup
round-trip).inat://rate-limits — documented iNaturalist API rate-limit
policy and how this server honours it.| Scenario | What this MCP adds |
|---|---|
Hiker mails in a tick (plan/04-data-flows.md Scenario A) |
The Walker lab gets the specimen; iNaturalist gives a near-real-time photo stream of other ticks observed in the same area in the same week. The Triage Agent can show “4 other brown-dog-tick photos within 25 km in the last 30 days” on the submission confirmation screen. |
| AZGFD wildlife mortality (Scenario B) | When an agency reports a die-off of prairie dogs in Apache County, this MCP gives the historical iNaturalist baseline of Cynomys gunnisoni sightings in the same place. |
| Knowledge-graph backfill | Every observation row carries an observation_id + url; the Knowledge Update Agent can dereference both back to the canonical iNaturalist record. |
The iNaturalist API requires every client to identify itself with a meaningful User-Agent header (API recommended practices). Anonymous traffic gets throttled or blocked, which would poison the shared rate-limit budget for the whole EpiHack stack.
So this server:
INAT_USER_AGENT is unset (the
__main__ entry point exits with code 2 and a clear error).INaturalistClient.Pick a UA that includes a project name, a version, and a contact:
INAT_USER_AGENT='epihack-az-2026/0.1 (contact: ops@example.org)'
Sourced from
api.inaturalist.org/v1/docs/
and the
iNaturalist API recommended practices
page:
id_above +
order_by=id).Retry-After header — the client
sleeps for that many seconds (capped at 60s) and retries once.For the full server-side policy text, query the
inat://rate-limits resource.
iNaturalist uses stable numeric IDs for both places and taxa. The defaults shipped here:
| Key | Default ID | Source |
|---|---|---|
| Arizona (US state) | 53 | confirm at https://api.inaturalist.org/v1/places/53 |
| Ticks (order Ixodida) | 47119 | confirm at https://www.inaturalist.org/taxa/47119 |
| Mosquitoes (family Culicidae) | 84738 | confirm at https://www.inaturalist.org/taxa/84738 |
| Fleas (order Siphonaptera) | 84377 | confirm at https://www.inaturalist.org/taxa/84377 |
| Rodents (order Rodentia) | 43698 | confirm at https://www.inaturalist.org/taxa/43698 |
| Rhipicephalus sanguineus (brown dog tick) | 84219 | |
| Dermacentor andersoni (Rocky Mountain wood tick) | 126099 | |
| Dermacentor variabilis (American dog tick) | 84223 | |
| Ixodes pacificus (Western black-legged tick) | 62366 | |
| Peromyscus maniculatus (deer mouse — hantavirus) | 46559 | |
| Cynomys gunnisoni (Gunnison’s prairie dog — plague) | 46211 | |
| Otospermophilus variegatus (rock squirrel — plague) | 73704 | |
| Sylvilagus audubonii (desert cottontail — tularemia) | 43130 |
Every ID is env-overridable (INAT_AZ_PLACE_ID, INAT_TAXON_*).
A contributor who finds a drifted ID can patch the env without a
code change. The inat_taxon_lookup tool is the authoritative
runtime check.
This server is mock-by-default in the same sense as
great-az-tick-check-mcp: the build
sandbox runs all tests without network access, against a canned
dataset of ~20 synthetic AZ observations covering ticks,
mosquitoes, fleas, deer mice, prairie dogs, rock squirrels, and
cottontails (see
src/inaturalist_mcp/canned_data.py).
Behaviour:
INAT_OFFLINE=1 to force the canned-data path (no HTTP
requests will be made).httpx.ConnectError / ReadError, the client
transparently falls back to the canned dataset and tags the
response with source: "canned" so the calling LLM knows which
it got. Live responses carry source: "live".This server is the citizen-science complement to the structured
great-az-tick-check-mcp:
great-az-tick-check-mcp = mail in a physical tick to the
Walker lab; deterministic species ID + PCR pathogen screen.inaturalist-mcp = scrape the public photo stream for the
same taxa in the same place + time window.The two together let the Triage Agent answer “is this tick the species I think it is?” with both a definitive lab path (mail it in) and a citizen-science prior (here are 4 other people’s photos of the same species in the same county in the last month).
iNaturalist observations are released under
Creative Commons licenses
(the most permissive default is CC BY-NC; observers can pick more
or less permissive). The platform is a joint initiative of the
California Academy of Sciences and the National Geographic Society.
Visit https://www.inaturalist.org/ for the full project, the GBIF data portal for the research-grade research-grade exports, and https://www.inaturalist.org/pages/api+recommended+practices for the API rules-of-the-road.
If you’re publishing analysis built on iNaturalist data, credit
individual observers (the user_login field on each row) per the
license attached to the photo.
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).INAT_USER_AGENT — the server refuses to start without it.cd mcp/inaturalist-mcp
uv sync
INAT_USER_AGENT='epihack-az-2026/0.1 (contact: ops@example.org)' \
uv run inaturalist-mcp # stdio (default)
MCP_TRANSPORT=streamable-http \
INAT_USER_AGENT='epihack-az-2026/0.1 (contact: ops@example.org)' \
uv run inaturalist-mcp # HTTP
cd mcp/inaturalist-mcp
uv run pytest
All tests are offline; no live API access required.
MIT, alongside the rest of epihack-2026.