inaturalist-mcp-server

Inaturalist Get Histogram

inaturalist_get_histogram

Read-only

Build a phenology histogram for a taxon in an area — which months, weeks, or years it is recorded in. The default month_of_year interval answers "when does this bloom or appear here" in twelve buckets; the absolute intervals (year, month, week, day, hour) bucket real dates and upstream applies a default start date to them. An area is given in exactly one form: place_id, the lat/lng/radius triple in kilometres, or a four-corner bounding box. Omit taxon_id to chart every taxon in the area. Narrow to one life stage or reproductive state with an annotation pair (term_id and term_value_id, e.g. Life Stage = Larva, or Flowers and Fruits = Flowers), or to broad groups with iconic_taxa. Defaults to research-grade, wild-only records and echoes those defaults back.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`d1`	No	Earliest observation date, YYYY-MM-DD. Inclusive. Must be on or before d2. With interval set to day or hour, a wide range can exceed the 800-bucket cap — narrow d1/d2 to reach buckets past it.
`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.
`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.
`interval`	No	Bucketing. month_of_year and week_of_year fold every year together into a seasonal curve; the rest bucket absolute dates. day and hour over a wide date range can generate thousands of buckets — the response is capped at 800, kept from the start of the range; narrow d1/d2 or use a coarser interval to see the rest.	month_of_year
`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. Omit to chart every taxon in the area. Resolve a name to an id with inaturalist_resolve_name.
`date_field`	No	Which date to bucket by: when the organism was observed, or when the record was uploaded.	observed
`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 bucket cap that was applied.
`error`	No	Present when the call failed. Absent on success.
`shown`	No	How many buckets this response carries.
`total`	No	Sum of every bucket count upstream returned, including buckets past the cap that are not in the buckets array.
`notice`	No	Guidance when every bucket came back zero, or when the cap was reached.
`buckets`	No	Every bucket upstream returned, in order, including the zero ones — up to 800, the first in upstream key order. See the truncated/shown/cap enrichment when more exist.
`interval`	No	The bucketing that was applied.
`truncated`	No	True when upstream returned more than 800 buckets.
`applied_filters`	No	The server-applied defaults that determine what this answer means.

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedSep 24, 2026

addedInput schema / properties / iconic_taxa

Added value: +{
+  "description": "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.",
+  "items": {
+    "enum": [
+      "Actinopterygii",
+      "Amphibia",
+      "Animalia",
+      "Arachnida",
+      "Aves",
+      "Chromista",
+      "Fungi",
+      "Insecta",
+      "Mammalia",
+      "Mollusca",
+      "Plantae",
+      "Protozoa",
+      "Reptilia",
+      "unknown"
+    ],
+    "type": "string"
+  },
+  "type": "array"
+}

addedInput schema / properties / term_id

Added value: +{
+  "description": "Annotation attribute ids, from inaturalist_list_reference topic controlled_terms — e.g. 1 for Life Stage.",
+  "items": {
+    "maximum": 9007199254740991,
+    "minimum": 1,
+    "type": "integer"
+  },
+  "type": "array"
+}

addedInput schema / properties / term_value_id

Added value: +{
+  "description": "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.",
+  "items": {
+    "maximum": 9007199254740991,
+    "minimum": 1,
+    "type": "integer"
+  },
+  "type": "array"
+}

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. `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",
-  "inverted_date_range",
-  "unknown_taxon_id"
-]New value: +[
+  "invalid_geography",
+  "inverted_date_range",
+  "unpaired_annotation_value",
+  "unknown_taxon_id"
+]

Changed7 schema fields changedSep 22, 2026

changedInput schema / properties / d1 / description

Previous value: -"Earliest observation date, YYYY-MM-DD. Inclusive. With interval set to day or hour, a wide range can exceed the 800-bucket cap — narrow d1/d2 to reach buckets past it."New value: +"Earliest observation date, YYYY-MM-DD. Inclusive. Must be on or before d2. With interval set to day or hour, a wide range can exceed the 800-bucket cap — narrow d1/d2 to reach buckets past it."

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. `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. `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",
-  "unknown_taxon_id"
-]New value: +[
+  "invalid_geography",
+  "inverted_date_range",
+  "unknown_taxon_id"
+]

First observedSep 20, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Annotations declare readOnlyHint=true and openWorldHint=true, so the safety profile is already covered. The description adds valuable behavioral context beyond annotations: it discloses that the upstream applies a default start date to absolute intervals, that the response is capped at 800 buckets kept from the start of the range, that a non-numeric place_id answers HTTP 500 upstream, and that term_value_id sent alone is ignored upstream. It also states defaults (research-grade, wild-only) and that they are echoed back. Minor gap: it doesn't describe the exact response shape, but an output schema exists, so that burden is lifted.

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

Conciseness4/5

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

The description is a single dense paragraph that front-loads the core purpose and default behavior, then covers area forms, taxon omission, annotation narrowing, and defaults. Every sentence earns its place, but the paragraph is long and packs many distinct facts together; a bit of structural separation (e.g., listing the three area forms) would improve scannability. Still, it is efficient and information-dense without fluff.

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 complex tool with 18 optional parameters, no required parameters, and an output schema, the description covers all the essential decision points: how to specify an area (three mutually exclusive forms), how to choose an interval, how to narrow by taxon/annotation/iconic_taxa, what the defaults are, and what upstream quirks to expect (500 km cap, 800-bucket cap, HTTP 500 on non-numeric place_id, ignored term_value_id). The output schema handles return values, and annotations handle safety. Nothing critical is missing for an agent to select and invoke this tool correctly.

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. The description adds meaning beyond the schema by explaining the semantic distinction between month_of_year/week_of_year (folded seasonal curve) and absolute intervals, by clarifying that the bounding box can cross the antimeridian, by noting the 500 km radius is a server-imposed verified ceiling, and by explaining that term_value_id requires term_id. It also gives concrete examples (Life Stage = Larva, Flowers and Fruits = Flowers) that make the annotation pair concept tangible. It doesn't fully compensate for the fact that 18 parameters is a lot, but the schema already documents each parameter well.

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 ('Build a phenology histogram') and names the resource (a taxon in an area) and the bucketing intervals (months, weeks, years). It clearly distinguishes this from sibling tools like inaturalist_get_species_counts or inaturalist_search_observations by focusing on temporal distribution rather than counts or raw observations.

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 explicitly states the area must be given in exactly one form (place_id, lat/lng/radius, or bounding box), explains when to omit taxon_id, and describes how to narrow by annotation pairs or iconic_taxa. It also gives concrete guidance on interval selection (month_of_year for seasonal questions, absolute intervals for real dates) and warns about the 800-bucket cap with day/hour intervals. This is rich, actionable usage guidance.

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.