inaturalist-mcp-server

Inaturalist List Reference

inaturalist_list_reference

Read-only

Decode the vocabularies the other iNaturalist tools take as input: annotation attributes and values, quality grades, license codes, taxonomic ranks, iconic taxa, and IUCN conservation-status codes. An unrecognized filter value is not rejected upstream — it silently returns nothing — so read the codes here before filtering. Note that the conservation codes are the normalised csi search filter; a taxon record’s own conservation_statuses[].status is authority-specific free text and reads differently. With topic controlled_terms and a taxon_id, the response also carries which annotations identifiers have actually recorded for that taxon, with counts.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`topic`	Yes	Which vocabulary to decode. controlled_terms is fetched live and cached; the rest are spec-derived static tables.
`taxon_id`	No	Add observed annotation usage for this taxon, ranked by how often each attribute/value pair has been recorded. Valid only with topic controlled_terms. Resolve a name to an id with inaturalist_resolve_name.

Output Schema

TableJSON Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`topic`	No	The vocabulary that was decoded.
`notice`	No	Guidance when the requested taxon has no recorded annotations yet.
`source`	No	"upstream" when the table was fetched from iNaturalist, "static" when spec-derived.
`entries`	No	The vocabulary, one entry per code or attribute.
`observed_usage`	No	Observed annotation usage for taxon_id, most-used first. Present only when taxon_id was given.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedSep 24, 2026

addedOutput schema / properties / observed_usage / items / properties / term_id

Added value: +{
+  "description": "Attribute id — pass it as term_id to filter search, species counts, or the histogram. Null when upstream omitted it.",
+  "type": [
+    "number",
+    "null"
+  ]
+}

addedOutput schema / properties / observed_usage / items / properties / term_value_id

Added value: +{
+  "description": "Value id — pass it as term_value_id alongside term_id. Null when upstream omitted it.",
+  "type": [
+    "number",
+    "null"
+  ]
+}

changedOutput schema / properties / observed_usage / items / properties / value / description

Previous value: -"Annotation value label."New value: +"Annotation value label. Labels repeat across attributes, so filter by the ids rather than the label."

changedOutput schema / properties / observed_usage / items / required

Previous value: -[
-  "attribute",
-  "value",
-  "count"
-]New value: +[
+  "attribute",
+  "term_id",
+  "value",
+  "term_value_id",
+  "count"
+]

First observedSep 20, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Beyond the readOnlyHint/openWorldHint annotations, the description discloses critical non-obvious behavior: an unrecognized filter value is not rejected upstream but silently returns nothing, and the conservation codes are normalized search-filter values rather than the taxon record's own free-text status. These are exactly the kind of behavioral traps an agent needs disclosed, and they are consistent with the annotations (no contradiction).

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?

Four sentences, all substantive: purpose, critical silent-failure warning, conservation-code normalization caveat, and the taxon_id interaction. The most important behavioral warning is front-loaded in sentence two. It is dense rather than bloated, with only a minor flaw: the unexplained 'csi' acronym assumes domain knowledge.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 2-parameter reference tool with an output schema, readOnly and openWorld annotations already present, the description covers purpose, the key usage trap, cross-tool routing, and the one subtle semantic distinction (conservation codes). The only gap is the unexplained 'csi' acronym and no elaboration on the controlled_terms live-cache behavior, which the schema already documents. Overall quite complete for the tool's complexity.

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 coverage is 100%, so the baseline is 3. The description adds real semantic value by clarifying the conservation_status_codes topic — that it is the normalized csi search filter, distinct from a taxon's own conservation_statuses[].status — which the schema's enum label does not convey. It also reinforces the cross-parameter constraint that taxon_id only applies with topic controlled_terms and states the count-carrying output behavior.

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 — 'Decode the vocabularies the other iNaturalist tools take as input' — and enumerates the exact vocabularies (annotation attributes/values, quality grades, license codes, ranks, iconic taxa, IUCN codes). This clearly differentiates it from the sibling data-retrieval tools (get_observation, search_observations, etc.) as the family's reference/decoder tool, with no tautology or ambiguity.

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: 'read the codes here before filtering', reinforced by the concrete consequence of not doing so (silent empty results). It also names an alternative tool for a related step ('Resolve a name to an id with inaturalist_resolve_name') and draws a precise when-not distinction between the normalized search-filter codes and the authority-specific conservation_statuses[].status field. Nothing is left to inference.

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.