inaturalist-mcp-server

Inaturalist Get Species Counts

inaturalist_get_species_counts

Read-only

Rank the distinct species recorded in an area and period, most-observed first — the "what lives here" answer, without paging through individual sightings. An area is given in exactly one form: place_id, the lat/lng/radius triple in kilometres, or a four-corner bounding box. Narrow to a clade by passing taxon_id, e.g. the birds of a park, or to one observer or one project by user_id, user_login, or project_id. Defaults to research-grade, wild-only records and echoes those defaults back. For the most active people rather than the most recorded species, use inaturalist_get_leaderboard.

Input Schema

TableJSON Schema

Name	Required	Description
`d1`	No	Earliest observation date, YYYY-MM-DD. Inclusive. Must be on or before d2.
`d2`	No	Latest observation date, YYYY-MM-DD. Inclusive.
`lat`	No	Latitude of the search centre, in decimal degrees. Requires lng and radius.
`lng`	No	Longitude of the search centre, in decimal degrees. Requires lat and radius.
`page`	No	Page number. Defaults to 1.
`nelat`	No	North-east corner latitude of the bounding box, at or north of swlat. All four corners or none.
`nelng`	No	North-east corner longitude of the bounding box. All four corners or none. West of swlng is accepted: it describes a box crossing the antimeridian.
`swlat`	No	South-west corner latitude of the bounding box. All four corners or none.
`swlng`	No	South-west corner longitude of the bounding box. All four corners or none.
`radius`	No	Search radius around lat/lng, in KILOMETRES, greater than 0. Requires lat and lng. The upstream publishes no bound; 500 is a verified ceiling this server imposes.
`captive`	No	Whether to include captive and cultivated records — zoo animals, garden plantings. Defaults to wild organisms only.
`term_id`	No	Annotation attribute ids, from inaturalist_list_reference topic controlled_terms — e.g. 1 for Life Stage.
`user_id`	No	Restrict to one observer, by numeric user id from inaturalist_resolve_name type user. Mutually exclusive with user_login.
`per_page`	No	Species per page, maximum 50. A ranked species costs roughly 860 bytes across structuredContent and the rendered text together, so 50 is a full page near 43 KB. Upstream would serve 500 in one page — raise page rather than asking for it.
`place_id`	No	Numeric iNaturalist place id from inaturalist_find_places. Mutually exclusive with the lat/lng/radius triple and the bounding box. A non-numeric value answers HTTP 500 upstream.
`taxon_id`	No	Restrict to this taxon and its descendants. Resolve a name to an id with inaturalist_resolve_name.
`project_id`	No	Restrict to observations in one project, by numeric project id from inaturalist_resolve_name type project.
`user_login`	No	Restrict to one observer, by login — the login on an inaturalist_resolve_name user candidate, a leaderboard entry, or an observation’s observer. Mutually exclusive with user_id.
`iconic_taxa`	No	Broad organism groups, by their scientific iconic-taxon name. A common-name value such as "Birds" matches nothing upstream, so only the listed values are accepted.
`quality_grade`	No	Identification confidence tiers to include. Defaults to research-grade only; adding "needs_id" roughly doubles the corpus and lowers identification confidence.
`term_value_id`	No	Annotation value ids, from the same attribute listing — e.g. 6 for Larva. Requires term_id; sent alone it is ignored upstream and the unfiltered corpus comes back.

Output Schema

TableJSON Schema

Name	Required	Description
`cap`	No	The per_page that was applied.
`error`	No	Present when the call failed. Absent on success.
`shown`	No	How many species this page carries.
`notice`	No	Guidance when nothing matched, when the page is past the last one holding species, or how to reach the species beyond this page.
`species`	No	The species, ranked by observation_count, most-observed first, each at its absolute position.
`truncated`	No	True when the page filled per_page and more species follow.
`total_results`	No	How many distinct species match. An estimate over a live index — it drifts between calls seconds apart.
`applied_filters`	No	The server-applied defaults that determine what this answer means.
`truncationCeiling`	No	Observation count of the last species shown. The ranking is descending, so no species left off this page exceeds it.

Schema Changelog

Changes observed during successful MCP inspections.

Changed9 schema fields changedSep 24, 2026

addedInput schema / properties / project_id

Added value: +{
+  "description": "Restrict to observations in one project, by numeric project id from inaturalist_resolve_name type project.",
+  "maximum": 9007199254740991,
+  "minimum": 1,
+  "type": "integer"
+}

addedInput schema / properties / user_id

Added value: +{
+  "description": "Restrict to one observer, by numeric user id from inaturalist_resolve_name type user. Mutually exclusive with user_login.",
+  "maximum": 9007199254740991,
+  "minimum": 1,
+  "type": "integer"
+}

addedInput schema / properties / user_login

Added value: +{
+  "description": "Restrict to one observer, by login — the login on an inaturalist_resolve_name user candidate, a leaderboard entry, or an observation’s observer. Mutually exclusive with user_id.",
+  "minLength": 1,
+  "type": "string"
+}

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `invalid_geography`: An area was given partially, in two forms at once, with a radius of 0 or less, or with nelat south of swlat. `inverted_date_range`: d1 is after d2. `unpaired_annotation_value`: term_value_id was supplied without term_id. `unknown_taxon_id`: iNaturalist answered 422 because the taxon_id does not exist. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_geography`: An area was given partially, in two forms at once, with a radius of 0 or less, or with nelat south of swlat. `inverted_date_range`: d1 is after d2. `unpaired_annotation_value`: term_value_id was supplied without term_id. `conflicting_observer`: user_id and user_login were both supplied. `unknown_taxon_id`: iNaturalist answered 422 because the taxon_id does not exist. `unknown_user`: iNaturalist answered 422 because the user_id or user_login names no observer. `unknown_project_id`: iNaturalist answered 422 because the project_id does not exist. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "invalid_geography",
-  "inverted_date_range",
-  "unpaired_annotation_value",
-  "unknown_taxon_id"
-]New value: +[
+  "invalid_geography",
+  "inverted_date_range",
+  "unpaired_annotation_value",
+  "conflicting_observer",
+  "unknown_taxon_id",
+  "unknown_user",
+  "unknown_project_id"
+]

changedOutput schema / properties / notice / description

Previous value: -"Guidance when nothing matched, or how to reach the species beyond this page."New value: +"Guidance when nothing matched, when the page is past the last one holding species, or how to reach the species beyond this page."

changedOutput schema / properties / species / description

Previous value: -"The species, ranked by observation_count, most-observed first."New value: +"The species, ranked by observation_count, most-observed first, each at its absolute position."

addedOutput schema / properties / species / items / properties / position

Added value: +{
+  "description": "Absolute place in this ranking, counted from page 1 — 7 is the seventh most-observed species. Not the taxonomic rank, which is rank.",
+  "type": "number"
+}

changedOutput schema / properties / species / items / required

Previous value: -[
-  "taxon_id",
-  "name",
-  "common_name",
-  "rank",
-  "iconic_taxon_name",
-  "observation_count"
-]New value: +[
+  "position",
+  "taxon_id",
+  "name",
+  "common_name",
+  "rank",
+  "iconic_taxon_name",
+  "observation_count"
+]

Changed7 schema fields changedSep 22, 2026

changedInput schema / properties / d1 / description

Previous value: -"Earliest observation date, YYYY-MM-DD. Inclusive."New value: +"Earliest observation date, YYYY-MM-DD. Inclusive. Must be on or before d2."

changedInput schema / properties / nelat / description

Previous value: -"North-east corner latitude of the bounding box. All four corners or none."New value: +"North-east corner latitude of the bounding box, at or north of swlat. All four corners or none."

changedInput schema / properties / nelng / description

Previous value: -"North-east corner longitude of the bounding box. All four corners or none."New value: +"North-east corner longitude of the bounding box. All four corners or none. West of swlng is accepted: it describes a box crossing the antimeridian."

changedInput schema / properties / radius / description

Previous value: -"Search radius around lat/lng, in KILOMETRES. Requires lat and lng. The upstream publishes no bound; 500 is a verified ceiling this server imposes."New value: +"Search radius around lat/lng, in KILOMETRES, greater than 0. Requires lat and lng. The upstream publishes no bound; 500 is a verified ceiling this server imposes."

removedInput schema / properties / radius / minimum
```
Removed value: -0
```

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `invalid_geography`: An area was given partially or in two forms at once. `unpaired_annotation_value`: term_value_id was supplied without term_id. `unknown_taxon_id`: iNaturalist answered 422 because the taxon_id does not exist. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_geography`: An area was given partially, in two forms at once, with a radius of 0 or less, or with nelat south of swlat. `inverted_date_range`: d1 is after d2. `unpaired_annotation_value`: term_value_id was supplied without term_id. `unknown_taxon_id`: iNaturalist answered 422 because the taxon_id does not exist. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "invalid_geography",
-  "unpaired_annotation_value",
-  "unknown_taxon_id"
-]New value: +[
+  "invalid_geography",
+  "inverted_date_range",
+  "unpaired_annotation_value",
+  "unknown_taxon_id"
+]

First observedSep 20, 2026

TDQS

A4.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds useful behavior beyond that: it returns a ranked aggregation rather than individual sightings, defaults to research-grade wild-only records, and 'echoes those defaults back' in the response. It does not cover error behavior or pagination details, but the output schema and annotations lower that burden.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences front-load the core purpose and answer shape, then cover area form exclusivity, common filters, defaults, and the key sibling alternative. Every clause earns its place and there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 21-parameter tool with a rich output schema and read-only/open-world annotations, the description covers all high-level decisions an agent must make: which area form, which optional filters, what defaults apply, and when to choose a different tool. Detailed parameter constraints live in the fully-covered schema, so nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3, but the description adds a valuable high-level grouping: the three mutually exclusive area forms, the clade filter, observer/project filters, and the leaderboard distinction. It composes parameters into coherent use-case patterns rather than merely repeating the schema's per-field notes.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Rank the distinct species recorded in an area and period, most-observed first,' and it crystallizes the intent as the 'what lives here' answer. It clearly distinguishes itself from individual-sighting retrieval with 'without paging through individual sightings' and from the leaderboard sibling by name.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives concrete selection guidance: exactly one area form is allowed, filters like taxon_id/user_id/user_login/project_id are listed, and defaults are stated. It explicitly redirects to inaturalist_get_leaderboard for a different question, giving the agent a clear branch between siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All inaturalist-mcp-server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.