inaturalist-mcp-server

<div align="center">
  <h1>@cyanheads/inaturalist-mcp-server</h1>
  <p><b>Search wildlife sightings, read identification threads, rank species by area, chart phenology, and find look-alike taxa from iNaturalist via MCP. STDIO or Streamable HTTP.</b>
  <div>10 Tools • 2 Resources</div>
  </p>
</div>

<div align="center">

[![Version](https://img.shields.io/badge/Version-0.1.2-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/inaturalist-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/inaturalist-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/inaturalist-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.0-blueviolet.svg?style=flat-square)](https://bun.sh/)

</div>

<div align="center">

[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/inaturalist-mcp-server/releases/latest/download/inaturalist-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=inaturalist-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvaW5hdHVyYWxpc3QtbWNwLXNlcnZlciJdfQ==) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22inaturalist-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Finaturalist-mcp-server%22%5D%7D)

[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)

</div>

<div align="center">

**Public Hosted Server:** [https://inaturalist.caseyjhand.com/mcp](https://inaturalist.caseyjhand.com/mcp)

</div>

---

## Overview

iNaturalist's index of 380M+ georeferenced citizen-science observations of plants, animals, and fungi. Search sightings by area, date, taxon, and annotation; read the community identification thread behind a record; chart when a taxon appears in a place; rank the species of an area; and check what a look-alike is most often confused with. Keyless and read-only, running as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

Composes with servers covering institutional specimen records, botanical nomenclature, and geocoding — this one contributes the observation, identification-thread, and phenology layer.

### Tools

| Tool | Description |
|:---|:---|
| `inaturalist_list_reference` | Decode the controlled vocabularies the other tools filter on — annotation attributes and values, quality grades, licences, ranks, iconic taxa, conservation-status codes |
| `inaturalist_resolve_name` | Resolve a common or scientific name to a taxon id, or a place, project, or observer name to its id, as ranked candidates |
| `inaturalist_find_places` | Resolve a place name to a place id, or list the places covering a map area, each with its bounding box and containment chain |
| `inaturalist_search_observations` | Search georeferenced sightings by area, date, taxon, quality grade, annotation, and conservation status |
| `inaturalist_get_observation` | Fetch up to 10 observations by id with their community identification thread and consensus taxon |
| `inaturalist_get_species_counts` | Rank the distinct species recorded in an area and period, most-observed first |
| `inaturalist_get_histogram` | Build a phenology histogram for a taxon in an area — which months, weeks, or years it is recorded in |
| `inaturalist_get_leaderboard` | Rank the most active observers or identifiers for an area, period, and taxon |
| `inaturalist_get_similar_species` | List the taxa a taxon is most often misidentified as, ranked by how many times identifiers made the correction |
| `inaturalist_get_taxon` | Fetch a taxon profile — taxonomic path, conservation listings by authority, encyclopedia summary, photos, and children |

### Resources

| Resource | Description |
|:---|:---|
| `inaturalist://taxa/{taxon_id}` | Taxon profile by numeric taxon id, as injectable context |
| `inaturalist://observations/{observation_id}` | One observation with its identification thread expanded, as injectable context |

Both resources mirror data also reachable through `inaturalist_get_taxon` and `inaturalist_get_observation` — useful for clients that don't surface MCP resources.

## Capability reference

### `inaturalist_list_reference` <sub>tool</sub>

- `topic` selects one table: `controlled_terms`, `quality_grades`, `licenses`, `ranks`, `iconic_taxa`, `conservation_status_codes`; `source` reports whether it came from iNaturalist or the published spec
- `taxon_id` applies only to `controlled_terms` and adds `observed_usage` — which annotation pairs identifiers have actually recorded for that taxon, with counts
- Every other tool's recovery hint routes here: an unrecognised filter value is not rejected upstream, it silently returns nothing

---

### `inaturalist_resolve_name` <sub>tool</sub>

- `type`: `taxon` (name-prefix autocomplete) or `place` / `project` / `user` / `any` (scored cross-kind search); `rank` narrows taxa only; `limit` 1–30 (default 10)
- Taxon lookup matches a name **prefix**, not words inside a name — "monarch" hits where "monarch butterfly" misses
- A miss is a result: `found: false` with `guidance` naming why, rather than an error
- Each candidate carries `kind` and `id` — the identifier every other tool takes

---

### `inaturalist_find_places` <sub>tool</sub>

- Exactly one of `q` (place-name prefix) or all four of `nelat`, `nelng`, `swlat`, `swlng`; neither or both fails as `invalid_geography`
- `q` returns `places[]`; the bounding box returns `standard[]` and `community[]` as separate lists
- Each place carries `bbox`, `place_type`, `admin_level`, `ancestor_place_ids`, `location`, and `slug`; boundary polygons are stripped, since one upstream response carries 247 KB of them
- `per_page` (1–30, default 10) binds the bounding-box arm only — the name-prefix endpoint publishes no page size, and its fixed page is disclosed through the truncation enrichment

---

### `inaturalist_search_observations` <sub>tool</sub>

- An area is given in exactly one form — `place_id`, the `lat`+`lng`+`radius` triple in kilometres (radius ≤ 500), or the four-corner bounding box; partial or mixed fails as `invalid_geography`
- Filters: `taxon_id`, `d1`/`d2`, `quality_grade`, `captive`, `term_id`+`term_value_id`, `iconic_taxa`, `hrank`/`lrank`, `csi`, `threatened`/`native`/`introduced`/`endemic`, `licensed`/`photo_licensed`, and `q`+`search_on`
- Defaults to `quality_grade: ["research"]` and `captive: false`, echoed back as `applied_filters` on every call
- `per_page` 1–25 (default 10); `page` walks the first 10,000 results and `cursor` continues past it — passing both fails, and a cursor forces an id ordering, which is echoed
- `include` expands `photos`, `annotations`, `sounds`. `identifications` and `comments` are deliberately absent — one thread measures 28 KB, so the thread lives on `inaturalist_get_observation`

---

### `inaturalist_get_observation` <sub>tool</sub>

- 1–10 ids per call, resolved in a single upstream request
- `include` defaults to `["identifications"]`; `comments`, `photos`, `annotations`, and `sounds` are also available
- Partial success: ids that resolve return in `observations`, the rest in `unresolved`; the call fails as `not_found` only when nothing resolved
- Adds `community_taxon` and `identification_disagreements_count` on top of the projected search record

---

### `inaturalist_get_species_counts` <sub>tool</sub>

- Distinct species for an area and period, ranked by `observation_count` — the "what lives here" answer without paging through individual sightings
- Same area forms and filters as the observation search; `taxon_id` narrows to a clade, such as the birds of a park
- `per_page` 1–50 (default 25), `page` for offset — upstream would serve 500 in one page, and the cap is sized by response bytes instead
- `truncationCeiling` carries the last count shown; the ranking is descending, so nothing left off the page exceeds it

---

### `inaturalist_get_histogram` <sub>tool</sub>

- `interval`: `month_of_year` (default) and `week_of_year` fold every year into one seasonal curve; `year`, `month`, `week`, `day`, and `hour` bucket absolute dates, to which upstream applies its own default start date
- `date_field`: `observed` (default) or `created`
- `taxon_id` is optional — omit it to chart every taxon in the area
- Returns every bucket upstream produced in order, zeros included, plus their `total` — computed across every bucket upstream returned, even past the cap. `day`/`hour` over a wide date range can generate thousands of buckets, so the response is capped at 800, kept from the start of the range, with `truncated`/`shown`/`cap` disclosing the cut

---

### `inaturalist_get_leaderboard` <sub>tool</sub>

- `kind`: `observers` (ranked by observations recorded, carrying `species_count`) or `identifiers` (identifications made); `count_metric` names what `count` measures
- `per_page` 1–250 (default 25), `page` for offset. Both endpoints rank only the top 500, so `page × per_page` past 500 fails as `leaderboard_window_exceeded` rather than returning a false zero-hit
- Takes the same area forms, `taxon_id`, `d1`/`d2`,