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

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	True returns captive and cultivated records only — zoo animals, garden plantings; false returns wild records only. Defaults to false.
`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.
`created_d1`	No	Earliest upload date, YYYY-MM-DD. Inclusive. Must be on or before created_d2.
`created_d2`	No	Latest upload date, YYYY-MM-DD. Inclusive.
`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, normalized to unique values in first-appearance order. 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

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.

Changed7 schema fields changedOct 26, 2026

changedInput schema / properties / captive / description

Previous value: -"Whether to include captive and cultivated records — zoo animals, garden plantings. Defaults to wild organisms only."New value: +"True returns captive and cultivated records only — zoo animals, garden plantings; false returns wild records only. Defaults to false."

addedInput schema / properties / created_d1

Added value: +{
+  "description": "Earliest upload date, YYYY-MM-DD. Inclusive. Must be on or before created_d2.",
+  "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+  "type": "string"
+}

addedInput schema / properties / created_d2

Added value: +{
+  "description": "Latest upload date, YYYY-MM-DD. Inclusive.",
+  "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+  "type": "string"
+}

changedInput schema / properties / quality_grade / description

Previous value: -"Identification confidence tiers to include. Defaults to research-grade only; adding \"needs_id\" roughly doubles the corpus and lowers identification confidence."New value: +"Identification confidence tiers to include, normalized to unique values in first-appearance order. Defaults to research-grade only; adding \"needs_id\" roughly doubles the corpus and lowers identification confidence."

changedOutput schema / properties / applied_filters / properties / captive / description

Previous value: -"Whether captive and cultivated records were included."New value: +"Captive-only when true, wild-only when false."

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: `unknown_place_id`: iNaturalist answered 422 because place_id does not exist. `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, or created_d1 is after created_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",
-  "unpaired_annotation_value",
-  "unknown_taxon_id"
-]New value: +[
+  "unknown_place_id",
+  "invalid_geography",
+  "inverted_date_range",
+  "unpaired_annotation_value",
+  "unknown_taxon_id"
+]

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.4/5.0

Behavior4/5

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

Annotations already establish read-only and open-world behavior, but the description adds meaningful operational context: default research-grade and wild-only filters, that defaults are echoed back, interval folding behavior, and upstream default start-date handling for absolute intervals. It does not mention the 800-bucket cap in the description (that is in schema), but overall it adds useful behavioral context beyond annotations.

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 front-loaded with the core purpose and then covers the important operational choices in dense but useful sentences. It is appropriately sized for a 20-parameter tool, though the long middle sentence packs many constraints together and could be slightly more scannable.

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 20-parameter read-only tool with an output schema and 100% schema coverage, the description covers the central behavior, interval semantics, area exclusivity, defaults, and filtering modes. Remaining details such as date bounds and created-date fields are adequately delegated to the schema.

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 would be 3, but the description adds conceptual meaning beyond field-level docs: it explains the default month_of_year seasonal curve, the exclusive area forms, annotation-pair narrowing with examples, and omitting taxon_id to chart all taxa. These additions improve parameter understanding without merely repeating the schema.

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 states a specific verb and resource: it builds a phenology histogram for a taxon in an area. It also clarifies the central output concept ('which months, weeks, or years it is recorded in'), which distinguishes it from sibling search/count tools without requiring schema inspection.

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

Usage Guidelines4/5

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

It gives clear usage context: default month_of_year answers seasonal bloom/appearance questions, absolute intervals bucket real dates, area must be supplied in exactly one form, and omitting taxon_id charts all taxa. It does not explicitly compare against alternatives such as inaturalist_get_species_counts or inaturalist_search_observations, so it stops short of full when/when-not 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.

Inaturalist Get Histogram

Input Schema

Output Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources