inaturalist-mcp-server

Inaturalist Search Observations

inaturalist_search_observations

Read-only

Search georeferenced wildlife sightings by area, date, taxon, quality grade, annotation, conservation status, observer, project, and licence. 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. page walks the first 10,000 results under any ordering; past 10,000, order by id descending (order_by "id", order "desc") and pass each page’s next_cursor as cursor.

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. Must be on or before d2.
`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, under any ordering. Defaults to 1. Mutually exclusive with cursor.
`hrank`	No	Highest (coarsest) taxonomic rank of the identification to accept. Must be at or above lrank; ranks compare by rank level.
`lrank`	No	Lowest (finest) taxonomic rank of the identification to accept. Equal to hrank for an exact-rank match.
`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.
`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 id-descending 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 order_by "id", order "desc".
`native`	No	Restrict to taxa native to the observation location.
`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.
`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.
`license`	No	Restrict to records whose own license_code is one of these, e.g. ["cc-by","cc0"] for reuse with attribution only. Decode the codes with inaturalist_list_reference topic licenses; all-rights-reserved records have no code to pass.
`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.
`licensed`	No	Restrict to records whose own license_code is not null — any licence, NonCommercial and NoDerivatives variants included. For specific licences, use license.
`order_by`	No	Sort field. Set "id" with order "desc" to walk past 10,000 results: that is the one ordering next_cursor continues, so it is the only one that issues a next_cursor. A cursor forces it.	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.
`project_id`	No	Restrict to observations in one project, by numeric project id from inaturalist_resolve_name type project.
`threatened`	No	Restrict to taxa considered threatened where observed.
`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.
`photo_license`	No	Restrict to records carrying at least one photo under one of these licence codes. Matched independently of the record’s own license_code, so check each photo’s license_code before reusing it.
`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, under any licence. For specific licences, use photo_license.

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, when the page is past the last one holding results, or how to continue past a full page.
`has_more`	No	True when this page filled per_page and more records follow. On the page path an exactly full final page is false; under a cursor, where the offset is unknown, every full page is true.
`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. Present only when has_more is true and the page was ordered by id descending; under any other ordering, raise page instead.
`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.

Changed15 schema fields changedSep 24, 2026

changedInput schema / properties / cursor / description

Previous value: -"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."New value: +"next_cursor from a previous id-descending 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 order_by \"id\", order \"desc\"."

addedInput schema / properties / license

Added value: +{
+  "description": "Restrict to records whose own license_code is one of these, e.g. [\"cc-by\",\"cc0\"] for reuse with attribution only. Decode the codes with inaturalist_list_reference topic licenses; all-rights-reserved records have no code to pass.",
+  "items": {
+    "enum": [
+      "cc-by",
+      "cc-by-nc",
+      "cc-by-nd",
+      "cc-by-sa",
+      "cc-by-nc-nd",
+      "cc-by-nc-sa",
+      "cc0"
+    ],
+    "type": "string"
+  },
+  "type": "array"
+}

changedInput schema / properties / licensed / description

Previous value: -"Restrict to records whose own license_code is not null."New value: +"Restrict to records whose own license_code is not null — any licence, NonCommercial and NoDerivatives variants included. For specific licences, use license."

changedInput schema / properties / order_by / description

Previous value: -"Sort field. Forced to id when cursor is supplied, since a cursor only continues an id ordering."New value: +"Sort field. Set \"id\" with order \"desc\" to walk past 10,000 results: that is the one ordering next_cursor continues, so it is the only one that issues a next_cursor. A cursor forces it."

changedInput schema / properties / page / description

Previous value: -"Page number within the first 10,000 results. Defaults to 1. Mutually exclusive with cursor."New value: +"Page number within the first 10,000 results, under any ordering. Defaults to 1. Mutually exclusive with cursor."

addedInput schema / properties / photo_license

Added value: +{
+  "description": "Restrict to records carrying at least one photo under one of these licence codes. Matched independently of the record’s own license_code, so check each photo’s license_code before reusing it.",
+  "items": {
+    "enum": [
+      "cc-by",
+      "cc-by-nc",
+      "cc-by-nd",
+      "cc-by-sa",
+      "cc-by-nc-nd",
+      "cc-by-nc-sa",
+      "cc0"
+    ],
+    "type": "string"
+  },
+  "type": "array"
+}

changedInput schema / properties / photo_licensed / description

Previous value: -"Restrict to records with at least one licensed photo."New value: +"Restrict to records with at least one licensed photo, under any licence. For specific licences, use photo_license."

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. `inverted_rank_range`: hrank is a finer rank than lrank. `result_window_exceeded`: page multiplied by per_page would reach past the upstream 10,000-result window. `conflicting_pagination`: Both page and cursor were supplied. `unpaired_annotation_value`: term_value_id was supplied without term_id. `search_on_without_query`: search_on was supplied without q. `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. `inverted_rank_range`: hrank is a finer rank than lrank. `result_window_exceeded`: page multiplied by per_page would reach past the upstream 10,000-result window. `conflicting_pagination`: Both page and cursor were supplied. `unpaired_annotation_value`: term_value_id was supplied without term_id. `search_on_without_query`: search_on was supplied without q. `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",
-  "inverted_rank_range",
-  "result_window_exceeded",
-  "conflicting_pagination",
-  "unpaired_annotation_value",
-  "search_on_without_query",
-  "unknown_taxon_id"
-]New value: +[
+  "invalid_geography",
+  "inverted_date_range",
+  "inverted_rank_range",
+  "result_window_exceeded",
+  "conflicting_pagination",
+  "unpaired_annotation_value",
+  "search_on_without_query",
+  "conflicting_observer",
+  "unknown_taxon_id",
+  "unknown_user",
+  "unknown_project_id"
+]

changedOutput schema / properties / has_more / description

Previous value: -"True when this page filled per_page, so more records follow."New value: +"True when this page filled per_page and more records follow. On the page path an exactly full final page is false; under a cursor, where the offset is unknown, every full page is true."

changedOutput schema / properties / next_cursor / description

Previous value: -"Pass back as cursor to continue past this page. Absent when has_more is false."New value: +"Pass back as cursor to continue past this page. Present only when has_more is true and the page was ordered by id descending; under any other ordering, raise page instead."

changedOutput schema / properties / notice / description

Previous value: -"Guidance when nothing matched, or how to continue past a full page."New value: +"Guidance when nothing matched, when the page is past the last one holding results, or how to continue past a full page."

Changed13 schema fields changedSep 24, 2026

changedOutput schema / properties / observations / items / properties / agreements / description

Previous value: -"How many identifications agree with the current taxon."New value: +"How many identifications currently agree with the community taxon."

changedOutput schema / properties / observations / items / properties / comments / description

Previous value: -"Discussion comments. Present when \"comments\" was included."New value: +"Discussion comments, cut to their first entries in upstream order (not strictly chronological) when they exceed the per-record share of a 40-entry budget. Present when \"comments\" was included."

addedOutput schema / properties / observations / items / properties / comments_shown

Added value: +{
+  "description": "How many of them comments carries. Below comments_total when the thread was cut. Present when \"comments\" was included.",
+  "type": "number"
+}

addedOutput schema / properties / observations / items / properties / comments_total

Added value: +{
+  "description": "How many comments upstream holds on the record. Present when \"comments\" was included.",
+  "type": "number"
+}

addedOutput schema / properties / observations / items / properties / description

Added value: +{
+  "description": "The observer’s own note on the sighting — host plant, behaviour, habitat, count. Third-party free text. Present on the by-id tool; null when the observer wrote none.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

changedOutput schema / properties / observations / items / properties / disagreements / description

Previous value: -"How many identifications disagree with the current taxon."New value: +"How many identifications currently disagree with the community taxon."

changedOutput schema / properties / observations / items / properties / identifications / description

Previous value: -"The identification thread. Present when \"identifications\" was included."New value: +"The identification thread, cut to its first entries in upstream order (roughly but not strictly chronological) when it exceeds the per-record share of a 40-entry budget. Present when \"identifications\" was included."

changedOutput schema / properties / observations / items / properties / identifications_count / description

Previous value: -"How many identifications the thread holds."New value: +"Upstream’s tally of identifications currently agreeing or disagreeing with the community taxon — agreements + disagreements. Not the thread size: it leaves out the observer’s own identification and any that neither agrees nor disagrees, such as a coarser or withdrawn one. The thread size is identifications_total, on inaturalist_get_observation."

addedOutput schema / properties / observations / items / properties / identifications_shown

Added value: +{
+  "description": "How many of them identifications carries. Below identifications_total when the thread was cut. Present when \"identifications\" was included.",
+  "type": "number"
+}

addedOutput schema / properties / observations / items / properties / identifications_total

Added value: +{
+  "description": "How many identifications upstream holds on the record — the thread size. Present when \"identifications\" was included.",
+  "type": "number"
+}

addedOutput schema / properties / observations / items / properties / observation_fields

Added value: +{
+  "description": "Observation-field values filled in on the record, usually by a project; fields left blank are dropped. Cut to the first filled fields in upstream order when they exceed the per-record share of a 40-entry budget. Present on the by-id tool.",
+  "items": {
+    "additionalProperties": false,
+    "description": "One filled observation field.",
+    "properties": {
+      "name": {
+        "description": "Field name, as its creator wrote it, e.g. \"Habitat_Description\".",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "value": {
+        "description": "The value filled in, verbatim.",
+        "type": "string"
+      }
+    },
+    "required": [
+      "name",
+      "value"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

addedOutput schema / properties / observations / items / properties / observation_fields_shown

Added value: +{
+  "description": "How many of them observation_fields carries. Below observation_fields_total when the list was cut. Present on the by-id tool.",
+  "type": "number"
+}

addedOutput schema / properties / observations / items / properties / observation_fields_total

Added value: +{
+  "description": "How many filled observation fields the record carries. Present on the by-id tool.",
+  "type": "number"
+}

Changed9 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 / hrank / description

Previous value: -"Highest taxonomic rank of the identification to accept."New value: +"Highest (coarsest) taxonomic rank of the identification to accept. Must be at or above lrank; ranks compare by rank level."

changedInput schema / properties / lrank / description

Previous value: -"Lowest taxonomic rank of the identification to accept."New value: +"Lowest (finest) taxonomic rank of the identification to accept. Equal to hrank for an exact-rank match."

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. `result_window_exceeded`: page multiplied by per_page would reach past the upstream 10,000-result window. `conflicting_pagination`: Both page and cursor were supplied. `unpaired_annotation_value`: term_value_id was supplied without term_id. `search_on_without_query`: search_on was supplied without q. `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. `inverted_rank_range`: hrank is a finer rank than lrank. `result_window_exceeded`: page multiplied by per_page would reach past the upstream 10,000-result window. `conflicting_pagination`: Both page and cursor were supplied. `unpaired_annotation_value`: term_value_id was supplied without term_id. `search_on_without_query`: search_on was supplied without q. `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",
-  "result_window_exceeded",
-  "conflicting_pagination",
-  "unpaired_annotation_value",
-  "search_on_without_query",
-  "unknown_taxon_id"
-]New value: +[
+  "invalid_geography",
+  "inverted_date_range",
+  "inverted_rank_range",
+  "result_window_exceeded",
+  "conflicting_pagination",
+  "unpaired_annotation_value",
+  "search_on_without_query",
+  "unknown_taxon_id"
+]

First observedSep 20, 2026

TDQS

A5/5.0

Behavior5/5

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

Annotations only declare readOnlyHint=true and openWorldHint=true, so the description must carry behavioral detail, and it does thoroughly. It discloses that the default research-grade/wild-only filtering is echoed on every call, that expanding identifications/comments is deliberately blocked (28 KB thread size), that pagination is limited to 10,000 under most orderings, that cursor forces id descending, and that 'term_value_id' sent alone is ignored upstream and returns the unfiltered corpus. It also documents a server-imposed 500 km radius ceiling when the upstream publishes no bound, and warns about HTTP 500 for non-numeric place_id. These are exactly the kind of operational gotchas an agent needs and go far beyond the 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?

Despite its length, the description is remarkably dense with non-redundant, high-value information. It front-loads the core purpose and area constraints, then efficiently covers pagination, expansion limits, and cost estimates. Every sentence earns its place – there is no filler or repetition. For a tool with 38 parameters, this is an appropriately concise and well-structured definition.

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 (38 parameters, many mutual exclusions, pagination edge cases, cost considerations) and that an output schema exists, the description is complete. It covers the area forms, defaults, expansion prohibitions, pagination strategy, cost guidance, and key parameter relationships. It also references companion tools for resolving IDs and licenses, leaving no obvious gap an agent would need to discover at runtime. The presence of an output schema means the description need not detail return fields, which it appropriately does not.

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

Parameters5/5

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

Schema coverage is 100% and each parameter already has a description, but the tool description adds substantial value beyond that baseline. For example, per_page explains the cost in KB and advises using page/cursor rather than larger pages; radius clarifies the 500 km server-imposed ceiling; cursor explains it is sent as id_below; include advises checking photo_count/sound_count first; and term_value_id warns it is ignored unless term_id is present. These enrich parameter semantics far beyond the schema, guiding correct usage and cost awareness.

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 clear, specific purpose: 'Search georeferenced wildlife sightings by area, date, taxon, quality grade, annotation, conservation status, observer, project, and licence.' It specifies the return shape (projected record with coordinates, licence, first photo, identification counts) and distinguishes itself from the sibling inaturalist_get_observation by explicitly stating that identifications and comments are deliberately not expandable and should be fetched there. This differentiation is explicit and actionable.

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 and when-not-to-use guidance. It states the three mutually exclusive area forms, explains defaults (research-grade, wild-only), tells the agent to fetch details via inaturalist_get_observation for identifications/comments, and provides a precise pagination strategy beyond 10,000 results (order by id descending, use next_cursor). It also references companion tools like inaturalist_resolve_name and inaturalist_find_places for parameter resolution, making usage unambiguous.

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.