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. 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. 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. All four corners or none.
`nelng`	No	North-east corner longitude of the bounding box. All four corners or none.
`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. 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.
`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
`quality_grade`	No	Identification confidence tiers to include. Defaults to research-grade only; adding "needs_id" roughly doubles the corpus and lowers identification confidence.

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.

First observedSep 20, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Annotations already indicate read-only and open-world behavior, and the description adds meaningful context: the default interval is month_of_year, absolute intervals get a default start date upstream, and results echo defaults back. This goes beyond the schema by explaining upstream behavior and default semantics, which helps the agent anticipate responses.

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?

Four dense sentences, each earning its place: the tool's purpose, interval behavior, area specification, and default filtering. No filler or redundancy. The most important distinction — histogram vs raw observations — is front-loaded.

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?

Given 15 parameters, a rich input schema, an output schema, and safety annotations, the description covers the non-obvious aspects: what the buckets mean, the exact area forms, the default interval, and default record filters. Nothing essential for selecting and invoking the tool correctly is missing.

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

Parameters3/5

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

Schema coverage is 100%, with every parameter already described in detail. The description adds no parameter-level meaning beyond what the schema provides; it only restates the area exclusivity and taxon omission. This is a solid baseline-3 case where the schema carries the parameter documentation burden.

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?

Description starts with a specific verb-resource pair: 'Build a phenology histogram for a taxon in an area,' and immediately clarifies the output buckets: months, weeks, or years. This clearly differentiates it from sibling tools like get_species_counts or search_observations, which return counts or observation lists rather than a temporal histogram.

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?

The description gives clear context on when this tool is appropriate: to answer 'when does this bloom or appear here' with the default month_of_year interval. It also explains area selection constraints and the option to omit taxon_id, but it does not explicitly state when-not-to-use it or name an alternative tool for similar queries.

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.