inaturalist-mcp-server

Inaturalist Search Observations

inaturalist_search_observations

Read-only

Search georeferenced wildlife sightings by area, date, taxon, quality grade, annotation, and conservation status. Returns a projected record per sighting with coordinates, licence, first photo, and identification counts. An area is given in exactly one form — place_id, the lat/lng/radius triple in kilometres, or a four-corner bounding box — and defaults to research-grade, wild-only records, which are echoed back on every call. Identifications and comments are deliberately not expandable here (one thread is 28 KB); fetch them for specific records with inaturalist_get_observation. Results past 10,000 need the cursor from the previous page rather than a higher page number.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`q`	No	Free text matched across observation properties.
`d1`	No	Earliest observation date, YYYY-MM-DD. Inclusive.
`d2`	No	Latest observation date, YYYY-MM-DD. Inclusive.
`csi`	No	IUCN-normalised conservation status codes to include, e.g. ["EN","CR"]. Decode them with inaturalist_list_reference topic conservation_status_codes.
`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 within the first 10,000 results. Defaults to 1. Mutually exclusive with cursor.
`hrank`	No	Highest taxonomic rank of the identification to accept.
`lrank`	No	Lowest taxonomic rank of the identification to accept.
`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.
`order`	No	Sort direction.	desc
`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.
`cursor`	No	next_cursor from a previous page, to continue past the 10,000-result window — a positive integer observation id, sent upstream as id_below. Mutually exclusive with page, and forces an id ordering.
`native`	No	Restrict to taxa native to the observation location.
`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.
`endemic`	No	Restrict to taxa endemic to the observation location.
`include`	No	Embedded arrays to expand per record. Check photo_count and sound_count first — expanding costs context.
`term_id`	No	Annotation attribute ids, from inaturalist_list_reference topic controlled_terms — e.g. 1 for Life Stage.
`licensed`	No	Restrict to records whose own license_code is not null.
`order_by`	No	Sort field. Forced to id when cursor is supplied, since a cursor only continues an id ordering.	observed_on
`per_page`	No	Records per page, maximum 25. A projected record costs roughly 1.9 KB across structuredContent and the rendered text together, so 25 is a full page near 49 KB and the default of 10 near 20 KB. Walk further with page or cursor rather than a larger page.
`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.
`search_on`	No	Narrow what q matches against. Requires q.
`introduced`	No	Restrict to taxa introduced to the observation location.
`threatened`	No	Restrict to taxa considered threatened where 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.
`photo_licensed`	No	Restrict to records with at least one licensed photo.

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 records this page carries.
`notice`	No	Guidance when nothing matched, or how to continue past a full page.
`has_more`	No	True when this page filled per_page, so more records follow.
`truncated`	No	True when the page filled per_page and more records follow.
`next_cursor`	No	Pass back as cursor to continue past this page. Absent when has_more is false.
`observations`	No	The matching sightings, projected.
`total_results`	No	How many records upstream reports as matching. An estimate over a live index — it drifts between calls seconds apart.
`applied_filters`	No	The server-applied defaults and overrides that determine what this answer means.

Schema Changelog

Changes observed during successful MCP inspections.

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 declare readOnlyHint=true and openWorldHint=true, so the safety profile is already covered. The description adds meaningful behavioral context beyond annotations: default research-grade/wild-only records are 'echoed back on every call', identifications/comments are deliberately not expandable, and the 10,000-result cursor behavior. It also discloses the upstream HTTP 500 for non-numeric place_id in the schema. Minor gap: it doesn't explicitly state that results are sorted by observed_on desc by default, but that is in the schema. A 4 is appropriate because the description adds substantial behavioral context without contradicting annotations.

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?

The description is a compact paragraph that front-loads the core purpose and return shape, then packs the most decision-relevant constraints (area exclusivity, defaults, non-expandable threads, cursor pagination) into four sentences. Every sentence earns its place; there is no filler or repetition of schema content.

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 the tool's complexity (33 parameters, no required params, output schema present), the description covers the critical operational constraints: area selection exclusivity, default filters, pagination beyond 10,000, and the cost/context tradeoff of per_page and include. The output schema exists, so return values need not be described. Sibling routing is provided. Nothing essential for correct invocation 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. The description adds value beyond the schema by explaining the area exclusivity rule, the cursor-vs-page mutual exclusion, the per_page context-cost warning (1.9 KB per record), and the default research-grade/wild-only behavior. It also clarifies that term_value_id requires term_id and that iconic_taxa common names match nothing. This is above the baseline but not a 5 because the description doesn't enumerate every parameter's semantics; it relies on the schema for most field-level details.

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: 'Search georeferenced wildlife sightings' and enumerates the filter dimensions (area, date, taxon, quality grade, annotation, conservation status). It also states the return shape ('projected record per sighting with coordinates, licence, first photo, and identification counts'), which distinguishes it from sibling tools like inaturalist_get_observation or inaturalist_get_species_counts. The scope is unambiguous.

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 explicit when-to-use guidance: it names the sibling inaturalist_get_observation for fetching identifications/comments, explains why (28 KB thread size), and states the area constraint ('exactly one form'). It also gives a concrete pagination rule ('Results past 10,000 need the cursor... rather than a higher page number'). This is strong routing and exclusion 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.