io.github.cyanheads/inaturalist-mcp-server

Official10 toolsLive

by cyanheads · TypeScript

Search iNaturalist sightings, identification threads, phenology, and look-alike species.

iaturalist-mcp-server (io.github.cyanheads/inaturalist-mcp-server)

The iaturalist-mcp-server is an MCP server that searches iNaturalist sightings. It also supports identification threads, phenology data, and look-alike species information. The server is described under the slug io-github-cyanheads-inaturalist-mcp-server.

🛠️ Key Features

Search iNaturalist sightings
Identification threads
Phenology
Look-alike species

🚀 Use Cases

Locate sightings within iNaturalist
Reference or browse identification discussions
Retrieve phenology-related information
Compare species with similar (look-alike) candidates

⚡ Developer Benefits

Provides focused access to iNaturalist sightings and related context (threads, phenology, look-alikes)
Scoped to species identification and similarity lookups

⚠️ Limitations

Only the server description fields provided are used here; no tool list, capabilities, or constraints are specified in the provided data.

Topics

biodiversitybuncitizen-scienceinaturalistmcpmcp-servermodel-context-protocoltypescriptai-agentsai-toolscyanheadsnatural-historyobservationsspecieswildlife

Captured live from the server via tools/list.

inaturalist_list_reference

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.

Parameters2

topic	string	required	Which vocabulary to decode. controlled_terms is fetched live and cached; the rest are spec-derived static tables.
taxon_id	integer	optional	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.

Raw schema

{
  "type": "object",
  "properties": {
    "topic": {
      "type": "string",
      "enum": [
        "controlled_terms",
        "quality_grades",
        "licenses",
        "ranks",
        "iconic_taxa",
        "conservation_status_codes"
      ],
      "description": "Which vocabulary to decode. controlled_terms is fetched live and cached; the rest are spec-derived static tables."
    },
    "taxon_id": {
      "description": "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.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "topic"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

inaturalist_resolve_name

Resolve a common or scientific name to a taxon id, or a place, project, or observer name to its id. Returns ranked candidates carrying the identifiers every other tool takes. A miss is a result rather than a failure: found comes back false with guidance naming why. Taxon lookup matches a name PREFIX, not words inside a name, so "monarch butterfly" misses where "monarch" hits.

Parameters4

q	string	required	The name to resolve. On type "taxon" this is a name prefix or an exact taxon id; on the other types it is matched across the record text.
type	string	optional	Which kind of record to resolve. "taxon" uses the taxon autocomplete; the rest use the scored cross-kind search, and "any" searches every kind at once. For a place’s bounding box and containment chain rather than just its id, use inaturalist_find_places instead.
rank	string	optional	Restrict taxon candidates to one rank. Honoured only on type "taxon" — the cross-kind search has no rank filter.
limit	integer	optional	Maximum candidates to return, applied to every type.

Raw schema

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "The name to resolve. On type \"taxon\" this is a name prefix or an exact taxon id; on the other types it is matched across the record text."
    },
    "type": {
      "default": "taxon",
      "description": "Which kind of record to resolve. \"taxon\" uses the taxon autocomplete; the rest use the scored cross-kind search, and \"any\" searches every kind at once. For a place’s bounding box and containment chain rather than just its id, use inaturalist_find_places instead.",
      "type": "string",
      "enum": [
        "taxon",
        "place",
        "project",
        "user",
        "any"
      ]
    },
    "rank": {
      "description": "Restrict taxon candidates to one rank. Honoured only on type \"taxon\" — the cross-kind search has no rank filter.",
      "type": "string",
      "enum": [
        "stateofmatter",
        "kingdom",
        "phylum",
        "subphylum",
        "superclass",
        "class",
        "subclass",
        "superorder",
        "order",
        "suborder",
        "infraorder",
        "superfamily",
        "epifamily",
        "family",
        "subfamily",
        "supertribe",
        "tribe",
        "subtribe",
        "genus",
        "genushybrid",
        "species",
        "hybrid",
        "subspecies",
        "variety",
        "form"
      ]
    },
    "limit": {
      "default": 10,
      "description": "Maximum candidates to return, applied to every type.",
      "type": "integer",
      "minimum": 1,
      "maximum": 30
    }
  },
  "required": [
    "q"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

inaturalist_find_places

Resolve a place name to a place id, or list the places containing a map area. Pass q to match a place-name PREFIX, or all four of nelat, nelng, swlat and swlng to list every place covering that box — exactly one of the two, never both. Each result carries the bounding box, place type, and containment chain an area search needs. Place geometry is stripped: a single nearby response carries 247 KB of boundary polygons upstream, none of which reaches the caller.

Parameters6

q	string	optional	Place-name prefix to search. Matches the start of a name, not words inside it. Mutually exclusive with the bounding box.
nelat	number	optional	North-east corner latitude of the map area, at or north of swlat. All four corners or none.
nelng	number	optional	North-east corner longitude of the map area. All four corners or none. West of swlng is accepted: it describes a box crossing the antimeridian.
swlat	number	optional	South-west corner latitude of the map area. All four corners or none.
swlng	number	optional	South-west corner longitude of the map area. All four corners or none.
per_page	integer	optional	Maximum places per list. Honoured on the bounding-box arm only, where it bounds the standard and community lists separately, so up to twice this many places come back. The name-prefix endpoint publishes no page size and returns a fixed page.

Raw schema

{
  "type": "object",
  "properties": {
    "q": {
      "description": "Place-name prefix to search. Matches the start of a name, not words inside it. Mutually exclusive with the bounding box.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "nelat": {
      "description": "North-east corner latitude of the map area, at or north of swlat. All four corners or none.",
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "nelng": {
      "description": "North-east corner longitude of the map area. All four corners or none. West of swlng is accepted: it describes a box crossing the antimeridian.",
      "type": "number",
      "minimum": -180,
      "maximum": 180
    },
    "swlat": {
      "description": "South-west corner latitude of the map area. All four corners or none.",
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "swlng": {
      "description": "South-west corner longitude of the map area. All four corners or none.",
      "type": "number",
      "minimum": -180,
      "maximum": 180
    },
    "per_page": {
      "default": 10,
      "description": "Maximum places per list. Honoured on the bounding-box arm only, where it bounds the standard and community lists separately, so up to twice this many places come back. The name-prefix endpoint publishes no page size and returns a fixed page.",
      "type": "integer",
      "minimum": 1,
      "maximum": 30
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

inaturalist_search_observations

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.

Parameters38

place_id	integer	optional	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.
lat	number	optional	Latitude of the search centre, in decimal degrees. Requires lng and radius.
lng	number	optional	Longitude of the search centre, in decimal degrees. Requires lat and radius.
radius	number	optional	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.
nelat	number	optional	North-east corner latitude of the bounding box, at or north of swlat. All four corners or none.
nelng	number	optional	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	number	optional	South-west corner latitude of the bounding box. All four corners or none.
swlng	number	optional	South-west corner longitude of the bounding box. All four corners or none.
taxon_id	integer	optional	Restrict to this taxon and its descendants. Resolve a name to an id with inaturalist_resolve_name.
d1	string	optional	Earliest observation date, YYYY-MM-DD. Inclusive. Must be on or before d2.
d2	string	optional	Latest observation date, YYYY-MM-DD. Inclusive.
quality_grade	array	optional	Identification confidence tiers to include. Defaults to research-grade only; adding "needs_id" roughly doubles the corpus and lowers identification confidence.
captive	boolean	optional	Whether to include captive and cultivated records — zoo animals, garden plantings. Defaults to wild organisms only.
term_id	array	optional	Annotation attribute ids, from inaturalist_list_reference topic controlled_terms — e.g. 1 for Life Stage.
term_value_id	array	optional	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.
iconic_taxa	array	optional	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.
user_id	integer	optional	Restrict to one observer, by numeric user id from inaturalist_resolve_name type user. Mutually exclusive with user_login.
user_login	string	optional	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.
project_id	integer	optional	Restrict to observations in one project, by numeric project id from inaturalist_resolve_name type project.
hrank	string	optional	Highest (coarsest) taxonomic rank of the identification to accept. Must be at or above lrank; ranks compare by rank level.
lrank	string	optional	Lowest (finest) taxonomic rank of the identification to accept. Equal to hrank for an exact-rank match.
csi	array	optional	IUCN-normalised conservation status codes to include, e.g. ["EN","CR"]. Decode them with inaturalist_list_reference topic conservation_status_codes.
threatened	boolean	optional	Restrict to taxa considered threatened where observed.
native	boolean	optional	Restrict to taxa native to the observation location.
introduced	boolean	optional	Restrict to taxa introduced to the observation location.
endemic	boolean	optional	Restrict to taxa endemic to the observation location.
licensed	boolean	optional	Restrict to records whose own license_code is not null — any licence, NonCommercial and NoDerivatives variants included. For specific licences, use license.
photo_licensed	boolean	optional	Restrict to records with at least one licensed photo, under any licence. For specific licences, use photo_license.
license	array	optional	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.
photo_license	array	optional	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.
q	string	optional	Free text matched across observation properties.
search_on	string	optional	Narrow what q matches against. Requires q.
order_by	string	optional	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.
order	string	optional	Sort direction.
page	integer	optional	Page number within the first 10,000 results, under any ordering. Defaults to 1. Mutually exclusive with cursor.
cursor	string	optional	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".
per_page	integer	optional	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.
include	array	optional	Embedded arrays to expand per record. Check photo_count and sound_count first — expanding costs context.

Raw schema

{
  "type": "object",
  "properties": {
    "place_id": {
      "description": "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.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "lat": {
      "description": "Latitude of the search centre, in decimal degrees. Requires lng and radius.",
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "lng": {
      "description": "Longitude of the search centre, in decimal degrees. Requires lat and radius.",
      "type": "number",
      "minimum": -180,
      "maximum": 180
    },
    "radius": {
      "description": "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.",
      "type": "number",
      "maximum": 500
    },
    "nelat": {
      "description": "North-east corner latitude of the bounding box, at or north of swlat. All four corners or none.",
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "nelng": {
      "description": "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.",
      "type": "number",
      "minimum": -180,
      "maximum": 180
    },
    "swlat": {
      "description": "South-west corner latitude of the bounding box. All four corners or none.",
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "swlng": {
      "description": "South-west corner longitude of the bounding box. All four corners or none.",
      "type": "number",
      "minimum": -180,
      "maximum": 180
    },
    "taxon_id": {
      "description": "Restrict to this taxon and its descendants. Resolve a name to an id with inaturalist_resolve_name.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "d1": {
      "description": "Earliest observation date, YYYY-MM-DD. Inclusive. Must be on or before d2.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "d2": {
      "description": "Latest observation date, YYYY-MM-DD. Inclusive.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "quality_grade": {
      "default": [
        "research"
      ],
      "description": "Identification confidence tiers to include. Defaults to research-grade only; adding \"needs_id\" roughly doubles the corpus and lowers identification confidence.",
      "minItems": 1,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "research",
          "needs_id",
          "casual"
        ]
      }
    },
    "captive": {
      "default": false,
      "description": "Whether to include captive and cultivated records — zoo animals, garden plantings. Defaults to wild organisms only.",
      "type": "boolean"
    },
    "term_id": {
      "description": "Annotation attribute ids, from inaturalist_list_reference topic controlled_terms — e.g. 1 for Life Stage.",
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 1,
        "maximum": 9007199254740991
      }
    },
    "term_value_id": {
      "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.",
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 1,
        "maximum": 9007199254740991
      }
    },
    "iconic_taxa": {
      "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.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "Actinopterygii",
          "Amphibia",
          "Animalia",
          "Arachnida",
          "Aves",
          "Chromista",
          "Fungi",
          "Insecta",
          "Mammalia",
          "Mollusca",
          "Plantae",
          "Protozoa",
          "Reptilia",
          "unknown"
        ]
      }
    },
    "user_id": {
      "description": "Restrict to one observer, by numeric user id from inaturalist_resolve_name type user. Mutually exclusive with user_login.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "user_login": {
      "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.",
      "type": "string",
      "minLength": 1
    },
    "project_id": {
      "description": "Restrict to observations in one project, by numeric project id from inaturalist_resolve_name type project.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "hrank": {
      "description": "Highest (coarsest) taxonomic rank of the identification to accept. Must be at or above lrank; ranks compare by rank level.",
      "type": "string",
      "enum": [
        "stateofmatter",
        "kingdom",
        "phylum",
        "subphylum",
        "superclass",
        "class",
        "subclass",
        "superorder",
        "order",
        "suborder",
        "infraorder",
        "superfamily",
        "epifamily",
        "family",
        "subfamily",
        "supertribe",
        "tribe",
        "subtribe",
        "genus",
        "genushybrid",
        "species",
        "hybrid",
        "subspecies",
        "variety",
        "form"
      ]
    },
    "lrank": {
      "description": "Lowest (finest) taxonomic rank of the identification to accept. Equal to hrank for an exact-rank match.",
      "type": "string",
      "enum": [
        "stateofmatter",
        "kingdom",
        "phylum",
        "subphylum",
        "superclass",
        "class",
        "subclass",
        "superorder",
        "order",
        "suborder",
        "infraorder",
        "superfamily",
        "epifamily",
        "family",
        "subfamily",
        "supertribe",
        "tribe",
        "subtribe",
        "genus",
        "genushybrid",
        "species",
        "hybrid",
        "subspecies",
        "variety",
        "form"
      ]
    },
    "csi": {
      "description": "IUCN-normalised conservation status codes to include, e.g. [\"EN\",\"CR\"]. Decode them with inaturalist_list_reference topic conservation_status_codes.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "LC",
          "NT",
          "VU",
          "EN",
          "CR",
          "EW",
          "EX"
        ]
      }
    },
    "threatened": {
      "description": "Restrict to taxa considered threatened where observed.",
      "type": "boolean"
    },
    "native": {
      "description": "Restrict to taxa native to the observation location.",
      "type": "boolean"
    },
    "introduced": {
      "description": "Restrict to taxa introduced to the observation location.",
      "type": "boolean"
    },
    "endemic": {
      "description": "Restrict to taxa endemic to the observation location.",
      "type": "boolean"
    },
    "licensed": {
      "description": "Restrict to records whose own license_code is not null — any licence, NonCommercial and NoDerivatives variants included. For specific licences, use license.",
      "type": "boolean"
    },
    "photo_licensed": {
      "description": "Restrict to records with at least one licensed photo, under any licence. For specific licences, use photo_license.",
      "type": "boolean"
    },
    "license": {
      "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.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "cc-by",
          "cc-by-nc",
          "cc-by-nd",
          "cc-by-sa",
          "cc-by-nc-nd",
          "cc-by-nc-sa",
          "cc0"
        ]
      }
    },
    "photo_license": {
      "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.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "cc-by",
          "cc-by-nc",
          "cc-by-nd",
          "cc-by-sa",
          "cc-by-nc-nd",
          "cc-by-nc-sa",
          "cc0"
        ]
      }
    },
    "q": {
      "description": "Free text matched across observation properties.",
      "type": "string",
      "minLength": 1
    },
    "search_on": {
      "description": "Narrow what q matches against. Requires q.",
      "type": "string",
      "enum": [
        "names",
        "tags",
        "description",
        "place"
      ]
    },
    "order_by": {
      "default": "observed_on",
      "description": "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.",
      "type": "string",
      "enum": [
        "created_at",
        "geo_score",
        "id",
        "observed_on",
        "random",
        "species_guess",
        "updated_at",
        "votes"
      ]
    },
    "order": {
      "default": "desc",
      "description": "Sort direction.",
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ]
    },
    "page": {
      "description": "Page number within the first 10,000 results, under any ordering. Defaults to 1. Mutually exclusive with cursor.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "cursor": {
      "description": "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\".",
      "type": "string",
      "pattern": "^[1-9]\\d*$"
    },
    "per_page": {
      "default": 10,
      "description": "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.",
      "type": "integer",
      "minimum": 1,
      "maximum": 25
    },
    "include": {
      "description": "Embedded arrays to expand per record. Check photo_count and sound_count first — expanding costs context.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "photos",
          "annotations",
          "sounds"
        ]
      }
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

inaturalist_get_observation

Fetch up to 10 observations by id with their community identification thread — who identified what, whether each identification agrees, and the consensus taxon the community landed on. The whole batch costs one upstream request, so resolving ten ids here is far cheaper than ten separate lookups. Records come back in the requested order. A missing id is reported per id in unresolved rather than failing the batch; the call fails only when nothing resolved. Long threads and long observation-field lists are cut to fit one response budget shared across the batch — up to 40 identifications, 40 comments, and 40 filled fields for a single id, 4 of each per record for ten — and every record reports the size of each array beside what it kept.

Parameters2

observation_id	array	required	Observation ids to fetch, 1 to 10. Find current ids for an area with inaturalist_search_observations.
include	array	optional	Embedded arrays to expand per record. identifications is the default and is what carries the thread; the others cost context, so check photo_count and sound_count first. identifications and comments — like the observation_fields every record carries — share a 40-entry budget across the batch: each record keeps at most 40 ÷ records returned entries per array (never fewer than 4), and reports identifications_total, comments_total, and observation_fields_total beside what it kept — request one id alone for the 40-entry view.

Raw schema

{
  "type": "object",
  "properties": {
    "observation_id": {
      "minItems": 1,
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 1,
        "maximum": 9007199254740991
      },
      "description": "Observation ids to fetch, 1 to 10. Find current ids for an area with inaturalist_search_observations."
    },
    "include": {
      "default": [
        "identifications"
      ],
      "description": "Embedded arrays to expand per record. identifications is the default and is what carries the thread; the others cost context, so check photo_count and sound_count first. identifications and comments — like the observation_fields every record carries — share a 40-entry budget across the batch: each record keeps at most 40 ÷ records returned entries per array (never fewer than 4), and reports identifications_total, comments_total, and observation_fields_total beside what it kept — request one id alone for the 40-entry view.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "identifications",
          "comments",
          "photos",
          "annotations",
          "sounds"
        ]
      }
    }
  },
  "required": [
    "observation_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

inaturalist_get_species_counts

Rank the distinct species recorded in an area and period, most-observed first — the "what lives here" answer, without paging through individual sightings. An area is given in exactly one form: place_id, the lat/lng/radius triple in kilometres, or a four-corner bounding box. Narrow to a clade by passing taxon_id, e.g. the birds of a park, or to one observer or one project by user_id, user_login, or project_id. Defaults to research-grade, wild-only records and echoes those defaults back. For the most active people rather than the most recorded species, use inaturalist_get_leaderboard.

Parameters21

place_id	integer	optional	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.
lat	number	optional	Latitude of the search centre, in decimal degrees. Requires lng and radius.
lng	number	optional	Longitude of the search centre, in decimal degrees. Requires lat and radius.
radius	number	optional	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.
nelat	number	optional	North-east corner latitude of the bounding box, at or north of swlat. All four corners or none.
nelng	number	optional	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	number	optional	South-west corner latitude of the bounding box. All four corners or none.
swlng	number	optional	South-west corner longitude of the bounding box. All four corners or none.
taxon_id	integer	optional	Restrict to this taxon and its descendants. Resolve a name to an id with inaturalist_resolve_name.
d1	string	optional	Earliest observation date, YYYY-MM-DD. Inclusive. Must be on or before d2.
d2	string	optional	Latest observation date, YYYY-MM-DD. Inclusive.
quality_grade	array	optional	Identification confidence tiers to include. Defaults to research-grade only; adding "needs_id" roughly doubles the corpus and lowers identification confidence.
captive	boolean	optional	Whether to include captive and cultivated records — zoo animals, garden plantings. Defaults to wild organisms only.
term_id	array	optional	Annotation attribute ids, from inaturalist_list_reference topic controlled_terms — e.g. 1 for Life Stage.
term_value_id	array	optional	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.
iconic_taxa	array	optional	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.
user_id	integer	optional	Restrict to one observer, by numeric user id from inaturalist_resolve_name type user. Mutually exclusive with user_login.
user_login	string	optional	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.
project_id	integer	optional	Restrict to observations in one project, by numeric project id from inaturalist_resolve_name type project.
page	integer	optional	Page number. Defaults to 1.
per_page	integer	optional	Species per page, maximum 50. A ranked species costs roughly 860 bytes across structuredContent and the rendered text together, so 50 is a full page near 43 KB. Upstream would serve 500 in one page — raise page rather than asking for it.

Raw schema

{
  "type": "object",
  "properties": {
    "place_id": {
      "description": "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.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "lat": {
      "description": "Latitude of the search centre, in decimal degrees. Requires lng and radius.",
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "lng": {
      "description": "Longitude of the search centre, in decimal degrees. Requires lat and radius.",
      "type": "number",
      "minimum": -180,
      "maximum": 180
    },
    "radius": {
      "description": "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.",
      "type": "number",
      "maximum": 500
    },
    "nelat": {
      "description": "North-east corner latitude of the bounding box, at or north of swlat. All four corners or none.",
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "nelng": {
      "description": "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.",
      "type": "number",
      "minimum": -180,
      "maximum": 180
    },
    "swlat": {
      "description": "South-west corner latitude of the bounding box. All four corners or none.",
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "swlng": {
      "description": "South-west corner longitude of the bounding box. All four corners or none.",
      "type": "number",
      "minimum": -180,
      "maximum": 180
    },
    "taxon_id": {
      "description": "Restrict to this taxon and its descendants. Resolve a name to an id with inaturalist_resolve_name.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "d1": {
      "description": "Earliest observation date, YYYY-MM-DD. Inclusive. Must be on or before d2.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "d2": {
      "description": "Latest observation date, YYYY-MM-DD. Inclusive.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "quality_grade": {
      "default": [
        "research"
      ],
      "description": "Identification confidence tiers to include. Defaults to research-grade only; adding \"needs_id\" roughly doubles the corpus and lowers identification confidence.",
      "minItems": 1,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "research",
          "needs_id",
          "casual"
        ]
      }
    },
    "captive": {
      "default": false,
      "description": "Whether to include captive and cultivated records — zoo animals, garden plantings. Defaults to wild organisms only.",
      "type": "boolean"
    },
    "term_id": {
      "description": "Annotation attribute ids, from inaturalist_list_reference topic controlled_terms — e.g. 1 for Life Stage.",
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 1,
        "maximum": 9007199254740991
      }
    },
    "term_value_id": {
      "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.",
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 1,
        "maximum": 9007199254740991
      }
    },
    "iconic_taxa": {
      "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.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "Actinopterygii",
          "Amphibia",
          "Animalia",
          "Arachnida",
          "Aves",
          "Chromista",
          "Fungi",
          "Insecta",
          "Mammalia",
          "Mollusca",
          "Plantae",
          "Protozoa",
          "Reptilia",
          "unknown"
        ]
      }
    },
    "user_id": {
      "description": "Restrict to one observer, by numeric user id from inaturalist_resolve_name type user. Mutually exclusive with user_login.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "user_login": {
      "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.",
      "type": "string",
      "minLength": 1
    },
    "project_id": {
      "description": "Restrict to observations in one project, by numeric project id from inaturalist_resolve_name type project.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "page": {
      "default": 1,
      "description": "Page number. Defaults to 1.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "per_page": {
      "default": 25,
      "description": "Species per page, maximum 50. A ranked species costs roughly 860 bytes across structuredContent and the rendered text together, so 50 is a full page near 43 KB. Upstream would serve 500 in one page — raise page rather than asking for it.",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

inaturalist_get_histogram

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.

Parameters18

taxon_id	integer	optional	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.
place_id	integer	optional	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.
lat	number	optional	Latitude of the search centre, in decimal degrees. Requires lng and radius.
lng	number	optional	Longitude of the search centre, in decimal degrees. Requires lat and radius.
radius	number	optional	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.
nelat	number	optional	North-east corner latitude of the bounding box, at or north of swlat. All four corners or none.
nelng	number	optional	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	number	optional	South-west corner latitude of the bounding box. All four corners or none.
swlng	number	optional	South-west corner longitude of the bounding box. All four corners or none.
interval	string	optional	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.
date_field	string	optional	Which date to bucket by: when the organism was observed, or when the record was uploaded.
d1	string	optional	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	string	optional	Latest observation date, YYYY-MM-DD. Inclusive.
quality_grade	array	optional	Identification confidence tiers to include. Defaults to research-grade only; adding "needs_id" roughly doubles the corpus and lowers identification confidence.
captive	boolean	optional	Whether to include captive and cultivated records — zoo animals, garden plantings. Defaults to wild organisms only.
term_id	array	optional	Annotation attribute ids, from inaturalist_list_reference topic controlled_terms — e.g. 1 for Life Stage.
term_value_id	array	optional	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.
iconic_taxa	array	optional	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.

Raw schema

{
  "type": "object",
  "properties": {
    "taxon_id": {
      "description": "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.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "place_id": {
      "description": "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.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "lat": {
      "description": "Latitude of the search centre, in decimal degrees. Requires lng and radius.",
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "lng": {
      "description": "Longitude of the search centre, in decimal degrees. Requires lat and radius.",
      "type": "number",
      "minimum": -180,
      "maximum": 180
    },
    "radius": {
      "description": "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.",
      "type": "number",
      "maximum": 500
    },
    "nelat": {
      "description": "North-east corner latitude of the bounding box, at or north of swlat. All four corners or none.",
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "nelng": {
      "description": "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.",
      "type": "number",
      "minimum": -180,
      "maximum": 180
    },
    "swlat": {
      "description": "South-west corner latitude of the bounding box. All four corners or none.",
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "swlng": {
      "description": "South-west corner longitude of the bounding box. All four corners or none.",
      "type": "number",
      "minimum": -180,
      "maximum": 180
    },
    "interval": {
      "default": "month_of_year",
      "description": "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.",
      "type": "string",
      "enum": [
        "year",
        "month",
        "week",
        "day",
        "hour",
        "month_of_year",
        "week_of_year"
      ]
    },
    "date_field": {
      "default": "observed",
      "description": "Which date to bucket by: when the organism was observed, or when the record was uploaded.",
      "type": "string",
      "enum": [
        "observed",
        "created"
      ]
    },
    "d1": {
      "description": "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.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "d2": {
      "description": "Latest observation date, YYYY-MM-DD. Inclusive.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "quality_grade": {
      "default": [
        "research"
      ],
      "description": "Identification confidence tiers to include. Defaults to research-grade only; adding \"needs_id\" roughly doubles the corpus and lowers identification confidence.",
      "minItems": 1,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "research",
          "needs_id",
          "casual"
        ]
      }
    },
    "captive": {
      "default": false,
      "description": "Whether to include captive and cultivated records — zoo animals, garden plantings. Defaults to wild organisms only.",
      "type": "boolean"
    },
    "term_id": {
      "description": "Annotation attribute ids, from inaturalist_list_reference topic controlled_terms — e.g. 1 for Life Stage.",
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 1,
        "maximum": 9007199254740991
      }
    },
    "term_value_id": {
      "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.",
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 1,
        "maximum": 9007199254740991
      }
    },
    "iconic_taxa": {
      "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.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "Actinopterygii",
          "Amphibia",
          "Animalia",
          "Arachnida",
          "Aves",
          "Chromista",
          "Fungi",
          "Insecta",
          "Mammalia",
          "Mollusca",
          "Plantae",
          "Protozoa",
          "Reptilia",
          "unknown"
        ]
      }
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

inaturalist_get_leaderboard

Rank the most active observers or identifiers for an area, period, and taxon — who knows this place or this group. kind selects which: observers are ranked by how many observations they recorded, identifiers by how many identifications they made. An area is given in exactly one form: place_id, the lat/lng/radius triple in kilometres, or a four-corner bounding box. Both endpoints rank only the top 500 entries, so page multiplied by per_page must stay at or below 500 — narrow the area, period, or taxon to bring someone further down into reach. For the most-recorded species rather than the most active people, use inaturalist_get_species_counts.

Parameters15

kind	string	required	Which leaderboard: "observers" ranks by observations recorded, "identifiers" by identifications made.
place_id	integer	optional	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.
lat	number	optional	Latitude of the search centre, in decimal degrees. Requires lng and radius.
lng	number	optional	Longitude of the search centre, in decimal degrees. Requires lat and radius.
radius	number	optional	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.
nelat	number	optional	North-east corner latitude of the bounding box, at or north of swlat. All four corners or none.
nelng	number	optional	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	number	optional	South-west corner latitude of the bounding box. All four corners or none.
swlng	number	optional	South-west corner longitude of the bounding box. All four corners or none.
taxon_id	integer	optional	Restrict to this taxon and its descendants. Resolve a name to an id with inaturalist_resolve_name.
d1	string	optional	Earliest observation date, YYYY-MM-DD. Inclusive. Must be on or before d2.
d2	string	optional	Latest observation date, YYYY-MM-DD. Inclusive.
quality_grade	array	optional	Identification confidence tiers to include. Defaults to research-grade only; adding "needs_id" roughly doubles the corpus and lowers identification confidence.
page	integer	optional	Page number. Defaults to 1.
per_page	integer	optional	Entries per page, maximum 250. An entry costs roughly 140 bytes across structuredContent and the rendered text together, so 250 is a full page near 34 KB — and two such pages cover the whole 500-entry window these endpoints rank.

Raw schema

{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "enum": [
        "observers",
        "identifiers"
      ],
      "description": "Which leaderboard: \"observers\" ranks by observations recorded, \"identifiers\" by identifications made."
    },
    "place_id": {
      "description": "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.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "lat": {
      "description": "Latitude of the search centre, in decimal degrees. Requires lng and radius.",
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "lng": {
      "description": "Longitude of the search centre, in decimal degrees. Requires lat and radius.",
      "type": "number",
      "minimum": -180,
      "maximum": 180
    },
    "radius": {
      "description": "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.",
      "type": "number",
      "maximum": 500
    },
    "nelat": {
      "description": "North-east corner latitude of the bounding box, at or north of swlat. All four corners or none.",
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "nelng": {
      "description": "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.",
      "type": "number",
      "minimum": -180,
      "maximum": 180
    },
    "swlat": {
      "description": "South-west corner latitude of the bounding box. All four corners or none.",
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "swlng": {
      "description": "South-west corner longitude of the bounding box. All four corners or none.",
      "type": "number",
      "minimum": -180,
      "maximum": 180
    },
    "taxon_id": {
      "description": "Restrict to this taxon and its descendants. Resolve a name to an id with inaturalist_resolve_name.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "d1": {
      "description": "Earliest observation date, YYYY-MM-DD. Inclusive. Must be on or before d2.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "d2": {
      "description": "Latest observation date, YYYY-MM-DD. Inclusive.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "quality_grade": {
      "default": [
        "research"
      ],
      "description": "Identification confidence tiers to include. Defaults to research-grade only; adding \"needs_id\" roughly doubles the corpus and lowers identification confidence.",
      "minItems": 1,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "research",
          "needs_id",
          "casual"
        ]
      }
    },
    "page": {
      "default": 1,
      "description": "Page number. Defaults to 1.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "per_page": {
      "default": 25,
      "description": "Entries per page, maximum 250. An entry costs roughly 140 bytes across structuredContent and the rendered text together, so 250 is a full page near 34 KB — and two such pages cover the whole 500-entry window these endpoints rank.",
      "type": "integer",
      "minimum": 1,
      "maximum": 250
    }
  },
  "required": [
    "kind"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

inaturalist_get_similar_species

List the taxa this one is most often misidentified as, ranked by how many times identifiers made the correction — the field-identification check before committing to a look-alike. Scope it to an area in exactly one form (place_id, the lat/lng/radius triple in kilometres, or a four-corner bounding box) to see the confusion set a specific region actually produces, or leave the area off for the global set. The taxon must be a genus or finer (genus, species, or below) — upstream keeps no confusion set for a family, order, or anything coarser. Resolve the organism name to a taxon id with inaturalist_resolve_name first.

Parameters14

taxon_id	integer	required	Numeric taxon id to find look-alikes for, at genus or finer — a genus, species, or subspecies; a family or anything coarser is refused. Resolve a name to an id with inaturalist_resolve_name.
place_id	integer	optional	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.
lat	number	optional	Latitude of the search centre, in decimal degrees. Requires lng and radius.
lng	number	optional	Longitude of the search centre, in decimal degrees. Requires lat and radius.
radius	number	optional	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.
nelat	number	optional	North-east corner latitude of the bounding box, at or north of swlat. All four corners or none.
nelng	number	optional	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	number	optional	South-west corner latitude of the bounding box. All four corners or none.
swlng	number	optional	South-west corner longitude of the bounding box. All four corners or none.
d1	string	optional	Earliest observation date, YYYY-MM-DD. Inclusive. Must be on or before d2.
d2	string	optional	Latest observation date, YYYY-MM-DD. Inclusive.
quality_grade	array	optional	Identification confidence tiers to include. Defaults to research-grade only; adding "needs_id" roughly doubles the corpus and lowers identification confidence.
captive	boolean	optional	Whether to include captive and cultivated records — zoo animals, garden plantings. Defaults to wild organisms only.
limit	integer	optional	Maximum look-alikes to return. Applied in-process — the upstream endpoint publishes no page size and returns its whole confusion set.

Raw schema

{
  "type": "object",
  "properties": {
    "taxon_id": {
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991,
      "description": "Numeric taxon id to find look-alikes for, at genus or finer — a genus, species, or subspecies; a family or anything coarser is refused. Resolve a name to an id with inaturalist_resolve_name."
    },
    "place_id": {
      "description": "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.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "lat": {
      "description": "Latitude of the search centre, in decimal degrees. Requires lng and radius.",
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "lng": {
      "description": "Longitude of the search centre, in decimal degrees. Requires lat and radius.",
      "type": "number",
      "minimum": -180,
      "maximum": 180
    },
    "radius": {
      "description": "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.",
      "type": "number",
      "maximum": 500
    },
    "nelat": {
      "description": "North-east corner latitude of the bounding box, at or north of swlat. All four corners or none.",
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "nelng": {
      "description": "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.",
      "type": "number",
      "minimum": -180,
      "maximum": 180
    },
    "swlat": {
      "description": "South-west corner latitude of the bounding box. All four corners or none.",
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "swlng": {
      "description": "South-west corner longitude of the bounding box. All four corners or none.",
      "type": "number",
      "minimum": -180,
      "maximum": 180
    },
    "d1": {
      "description": "Earliest observation date, YYYY-MM-DD. Inclusive. Must be on or before d2.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "d2": {
      "description": "Latest observation date, YYYY-MM-DD. Inclusive.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "quality_grade": {
      "default": [
        "research"
      ],
      "description": "Identification confidence tiers to include. Defaults to research-grade only; adding \"needs_id\" roughly doubles the corpus and lowers identification confidence.",
      "minItems": 1,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "research",
          "needs_id",
          "casual"
        ]
      }
    },
    "captive": {
      "default": false,
      "description": "Whether to include captive and cultivated records — zoo animals, garden plantings. Defaults to wild organisms only.",
      "type": "boolean"
    },
    "limit": {
      "default": 20,
      "description": "Maximum look-alikes to return. Applied in-process — the upstream endpoint publishes no page size and returns its whole confusion set.",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  },
  "required": [
    "taxon_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

inaturalist_get_taxon

Fetch a taxon profile: the taxonomic path, per-authority conservation listings, the encyclopedia summary, the photo gallery, immediate children, and observation counts. Resolve a name to a taxon id with inaturalist_resolve_name first. The upstream record is 95 KB for a common species, so it is projected before anything else happens; a taxon that still overflows comes back as an outline of its sections with their byte sizes, and naming those sections in a re-call returns only those. The valid section names are summary, taxonomy, children, conservation, photos, and encyclopedia.

Parameters2

taxon_id	integer	required	Numeric taxon id. A non-numeric value answers HTTP 422 with an empty message upstream, so the integer is enforced here. Resolve a name to an id with inaturalist_resolve_name.
sections	array	optional	Sections to return: summary, taxonomy, children, conservation, photos, encyclopedia. Omit for the whole profile, or an outline of it when it overflows. A selection returns whatever it names, at whatever size, so sum the byte sizes from the outline before asking for several.

Raw schema

{
  "type": "object",
  "properties": {
    "taxon_id": {
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991,
      "description": "Numeric taxon id. A non-numeric value answers HTTP 422 with an empty message upstream, so the integer is enforced here. Resolve a name to an id with inaturalist_resolve_name."
    },
    "sections": {
      "description": "Sections to return: summary, taxonomy, children, conservation, photos, encyclopedia. Omit for the whole profile, or an outline of it when it overflows. A selection returns whatever it names, at whatever size, so sum the byte sizes from the outline before asking for several.",
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      }
    }
  },
  "required": [
    "taxon_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

README.md27 KBView on GitHub

@cyanheads/inaturalist-mcp-server

Search wildlife sightings, read identification threads, rank species by area, chart phenology, and find look-alike taxa from iNaturalist via MCP. STDIO or Streamable HTTP.

10 Tools • 2 Resources

Version MCP SDK TypeScript

Public Hosted Server: https://inaturalist.caseyjhand.com/mcp

Overview

iNaturalist's index of 380M+ georeferenced citizen-science observations of plants, animals, and fungi. Search sightings by area, date, taxon, and annotation; read the community identification thread behind a record; chart when a taxon appears in a place; rank the species of an area; and check what a look-alike is most often confused with. Keyless and read-only, running as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

Composes with servers covering institutional specimen records, botanical nomenclature, and geocoding — this one contributes the observation, identification-thread, and phenology layer.

Tools

Tool	Description
`inaturalist_list_reference`	Decode the controlled vocabularies the other tools filter on — annotation attributes and values, quality grades, licences, ranks, iconic taxa, conservation-status codes
`inaturalist_resolve_name`	Resolve a common or scientific name to a taxon id, or a place, project, or observer name to its id, as ranked candidates
`inaturalist_find_places`	Resolve a place name to a place id, or list the places covering a map area, each with its bounding box and containment chain
`inaturalist_search_observations`	Search georeferenced sightings by area, date, taxon, quality grade, annotation, conservation status, observer, project, and licence
`inaturalist_get_observation`	Fetch up to 10 observations by id with their community identification thread and consensus taxon
`inaturalist_get_species_counts`	Rank the distinct species recorded in an area and period, most-observed first — optionally for one observer or one project
`inaturalist_get_histogram`	Build a phenology histogram for a taxon in an area — which months, weeks, or years it is recorded in
`inaturalist_get_leaderboard`	Rank the most active observers or identifiers for an area, period, and taxon
`inaturalist_get_similar_species`	List the taxa a genus-or-finer taxon is most often misidentified as, ranked by how many times identifiers made the correction
`inaturalist_get_taxon`	Fetch a taxon profile — taxonomic path, conservation listings by authority, encyclopedia summary, photos, and children

Resources

Resource	Description
`inaturalist://taxa/{taxon_id}`	Taxon profile by numeric taxon id, as injectable context
`inaturalist://observations/{observation_id}`	One observation with its identification thread expanded, as injectable context

Both resources mirror data also reachable through inaturalist_get_taxon and inaturalist_get_observation — useful for clients that don't surface MCP resources.

Capability reference

`inaturalist_list_reference` _tool

topic selects one table: controlled_terms, quality_grades, licenses, ranks, iconic_taxa, conservation_status_codes; source reports whether it came from iNaturalist or the published spec
taxon_id applies only to controlled_terms and adds observed_usage — which annotation pairs identifiers have actually recorded for that taxon, with counts. Each row carries term_id and term_value_id, ready to pass to the annotation filters; labels repeat across attributes ("Egg" is both a Life Stage and an Evidence of Presence value), so filter by the ids
Every other tool's recovery hint routes here: an unrecognised filter value is not rejected upstream, it silently returns nothing

`inaturalist_resolve_name` _tool

type: taxon (name-prefix autocomplete) or place / project / user / any (scored cross-kind search); rank narrows taxa only; limit 1–30 (default 10), applied in-process on every type
Taxon lookup matches a name prefix, not words inside a name — "monarch" hits where "monarch butterfly" misses
A miss is a result: found: false with guidance naming why, rather than an error
Each candidate carries kind and id — the identifier every other tool takes. A user candidate also carries login, the value leaderboard entries and an observation's observer relay; its name is the display name

`inaturalist_find_places` _tool

Exactly one of q (place-name prefix) or all four of nelat, nelng, swlat, swlng; neither or both fails as invalid_geography, as does a box with nelat south of swlat. A blank q reads as unset, and nelng west of swlng is an antimeridian-crossing box, not an error
q returns places[]; the bounding box returns standard[] and community[] as separate lists
Each place carries bbox, place_type, admin_level, ancestor_place_ids, location, and slug; boundary polygons are stripped, since one upstream response carries 247 KB of them
per_page (1–30, default 10) binds the bounding-box arm only, where it bounds standard[] and community[] separately, so cap is per_page × 2. The name-prefix endpoint publishes no page size, and its fixed page is disclosed through the truncation enrichment

`inaturalist_search_observations` _tool

An area is given in exactly one form — place_id, the lat+lng+radius triple in kilometres (0 < radius ≤ 500), or the four-corner bounding box with nelat at or north of swlat; partial, mixed, a zero radius, or an inverted box fails as invalid_geography
Filters: taxon_id, d1/d2, quality_grade, captive, term_id+term_value_id, iconic_taxa, hrank/lrank, csi, threatened/native/introduced/endemic, user_id or user_login, project_id, licensed/photo_licensed, license/photo_license, and q+search_on
user_id, user_login, and project_id come from inaturalist_resolve_name (a login also rides leaderboard entries and every observation's observer). Passing both observer forms fails as conflicting_observer; an unknown observer or project fails as unknown_user or unknown_project_id
license and photo_license take licence codes — cc0, cc-by, cc-by-nc, cc-by-nd, cc-by-sa, cc-by-nc-nd, cc-by-nc-sa, any case — joined as OR, so ["cc-by","cc0"] finds sightings reusable with attribution only. photo_license matches a record with any photo under the code, independently of the record's own licence. licensed/photo_licensed only test for a non-null licence
Ordered pairs are checked before the request: d1 after d2 fails as inverted_date_range (on every tool that takes dates), and an hrank finer than lrank as inverted_rank_range. Equal pairs are valid
Defaults to quality_grade: ["research"] and captive: false, echoed back as applied_filters on every call
per_page 1–25 (default 10); page walks the first 10,000 results under any ordering. Past that, order by id descending and pass each page's next_cursor as cursor — next_cursor is issued only on an id-descending page, since no other ordering can be continued by id. Passing page and cursor together fails, and a cursor forces the id ordering, which is echoed
A page past the last one holding results says so and names that page, rather than suggesting wider filters
include expands photos, annotations, sounds. identifications and comments are deliberately absent — one thread measures 28 KB, so the thread lives on inaturalist_get_observation

`inaturalist_get_observation` _tool

1–10 ids per call, resolved in a single upstream request
include defaults to ["identifications"]; comments, photos, annotations, and sounds are also available
Partial success: ids that resolve return in observations, the rest in unresolved; the call fails as not_found only when nothing resolved
Adds community_taxon, identification_disagreements_count, the observer's description, and filled observation_fields on top of the projected search record
Records come back in the requested order, unresolved ids left out in place
identifications, comments, and the filled observation_fields share a 40-entry budget across the batch: each record keeps its first max(4, floor(40 / records returned)) entries per array in upstream order — 40 for one id, 4 for ten — and reports identifications_total/identifications_shown, comments_total/comments_shown, and observation_fields_total/observation_fields_shown. A cut is named in the notice; request one id alone for the 40-entry view, or open the record's url for the full record. description is never cut
identifications_count is upstream's tally of identifications agreeing or disagreeing with the community taxon (agreements + disagreements), not the thread size — that is identifications_total

`inaturalist_get_species_counts` _tool

Distinct species for an area and period, ranked by observation_count — the "what lives here" answer without paging through individual sightings
Same area forms and filters as the observation search; taxon_id narrows to a clade, such as the birds of a park, and user_id/user_login or project_id to one observer's or one project's species list
per_page 1–50 (default 25), page for offset — upstream would serve 500 in one page, and the cap is sized by response bytes instead
Each row carries position, its absolute place in the ranking counted from page 1, and the rendered list is numbered from it — page 3 at 3 per page reads 7, 8, 9. rank stays the taxonomic rank
truncationCeiling carries the last count shown; the ranking is descending, so nothing left off the page exceeds it

`inaturalist_get_histogram` _tool

interval: month_of_year (default) and week_of_year fold every year into one seasonal curve; year, month, week, day, and hour bucket absolute dates, to which upstream applies its own default start date
date_field: observed (default) or created
taxon_id is optional — omit it to chart every taxon in the area
term_id+term_value_id chart one life stage or reproductive state, such as monarch larvae (Life Stage 1 = Larva 6) or a plant in flower (Flowers and Fruits 12 = Flowers 13); iconic_taxa narrows to broad groups. term_value_id without term_id fails as unpaired_annotation_value, and an all-zero curve names the annotation or group filter when one was set
Returns every bucket upstream produced in order, zeros included, plus their total — computed across every bucket upstream returned, even past the cap. day/hour over a wide date range can generate thousands of buckets, so the response is capped at 800, kept from the start of the range, with truncated/shown/cap disclosing the cut

`inaturalist_get_leaderboard` _tool

kind: observers (ranked by observations recorded, carrying species_count) or identifiers (identifications made); count_metric names what count measures
per_page 1–250 (default 25), page for offset. Both endpoints rank only the top 500, so page × per_page past 500 fails as leaderboard_window_exceeded rather than returning a false zero-hit
Takes the same area forms, taxon_id, d1/d2, and quality_grade as the observation search

`inaturalist_get_similar_species` _tool

The taxa a taxon_id is most often corrected from, ranked by misidentification_count — the field-identification check before committing to a look-alike
taxon_id must be a genus or finer; upstream keeps no confusion set for a family, order, or anything coarser, and the call fails as taxon_rank_too_coarse
An optional area, date range, quality_grade, and captive scope the confusion set to one region; omit them for the global set
limit 1–50 (default 20), applied in-process — the endpoint publishes no page size and returns its whole set

`inaturalist_get_taxon` _tool

One taxon_id. Returns kind: "full" with the projected profile, or kind: "outline" listing each section and its byte size when the projection still overflows the budget
Sections are summary, taxonomy, children, conservation, photos, encyclopedia; name them in sections to fetch a slice, and an unknown name fails as unknown_section
The upstream record is 95 KB for a common species — per-country checklist membership is dropped, listed_taxa_count kept as a scalar, and ancestors, children, and conservation entries trimmed to their identifying fields
A named section comes back whole at whatever size, so sum the outline's byte sizes before asking for several

`inaturalist://taxa/{taxon_id}` _resource

The projected taxon document as application/json, always whole — a resource read has no way to name sections, so use inaturalist_get_taxon when the outline path matters
taxon_id comes from inaturalist_resolve_name; cached for six hours, matching the service's taxon TTL

`inaturalist://observations/{observation_id}` _resource

One observation with its identification thread expanded, as application/json — the first 40 identifications and the first 40 filled observation fields in upstream order, each with its _total beside its _shown
observation_id comes from inaturalist_search_observations; cached for fifteen minutes, since a thread accrues identifications

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

iNaturalist-specific:

Keyless, read-only cover of the iNaturalist v1 API — observations, taxa, places, controlled terms, the similar-species graph, and the observer and identifier leaderboards
Every response is projected in-process. Upstream accepts and ignores its own fields= parameter, so a two-record observation search arrives at 95 KB, a full upstream page of 200 at 4.3 MB, and a common taxon record at 95 KB before anything is trimmed
Per-endpoint parameter allowlist — an unknown parameter name returns HTTP 200 and the entire global index, so nothing outside the allowlist is ever sent
In-process rejection of every input upstream would silently widen, narrow to zero, or fail on: a lone lat, an unparseable or impossible d1 such as 2026-02-30, d1 after d2, a term_value_id without its term_id, user_id with user_login, a licence code outside the seven, a zero radius, a box with nelat south of swlat, a page past the result window
Self-paced outbound traffic with a per-UTC-day request budget, since the API returns no rate-limit headers to react to

Agent-friendly output:

Applied defaults echoed on every call — quality_grade, captive, and the ordering a cursor forced — so an agent can see the filters that shaped its answer
Zero-hit notices name the filter most likely responsible and the tool that decodes it, instead of an empty list; a page past the end names the last page holding results instead
Truncation disclosed unconditionally: truncated, shown, and cap on every path, plus a truncationCeiling where a descending ranking supports one
Upstream free text — encyclopedia summaries, identification and comment bodies, place guesses, photo attributions — renders inside a markdown blockquote, marking it as third-party content rather than instruction

Licensing and attribution

The API is open; the records are not uniformly open.

license_code is relayed verbatim and is nullable. A null means all rights reserved — it is never coerced to "", "unknown", or a default licence, and the rendered text spells the null case out in words.
Photo attribution strings are relayed verbatim, never reformatted or shortened, and must be reproduced wherever the image is. A photo's own license_code is independent of its observation's.
open is derived from the hosting domain: true for inaturalist-open-data.s3.amazonaws.com, false for anything else, because an unrecognised host is not evidence of an open licence. A licence change moves a photo between hosts, so the flag describes fetch time rather than a permanent property.
Photos are linked, never proxied. No tool fetches image bytes or emits base64 image content — a URL with its attribution and licence is the whole contract.
obscured: true marks a locality, not a sighting position. iNaturalist withholds true coordinates for threatened taxa, and the server never sends an Authorization header, so hidden coordinates stay hidden.
Observer identity collapses to login. The upstream user object carries a real name, an ORCID, and counts; none of it is relayed.

Rate limits and response size

The published terms allow at most 100 requests per minute, ask clients to stay at or below 60, and ask for under 10,000 per day. No rate-limit headers come back, so pacing is entirely self-imposed: outbound requests start at least INATURALIST_MIN_REQUEST_INTERVAL_MS apart (1100 ms ≈ 54 per minute), at most INATURALIST_MAX_CONCURRENT_REQUESTS run in flight, and INATURALIST_DAILY_REQUEST_BUDGET bounds a UTC day. Exhausting the budget is a typed failure rather than a silent degradation.

Controlled terms (24 h), taxon profiles (6 h), places (6 h), the similar-species graph (6 h), and histograms (1 h) are cached in tenant-scoped storage. Observation search, species counts, leaderboards, and observation detail are never cached — freshness is what they are for.

Page-size maxima are sized by measured response bytes across structuredContent and the rendered text together, not by what upstream will serve:

Tool	Bytes per record	`per_page` max	Default	Upstream would serve
`inaturalist_search_observations`	~1,970	25	10	200
`inaturalist_get_species_counts`	~860	50	25	500
`inaturalist_get_leaderboard`	~140	250	25	500

Each default page fits the 24,000-byte budget a single document gets, and each full page fits 50,000. Nothing is unreachable at the lower caps — page walks the first 10,000 records under any ordering, and an id-descending walk continues past that by cursor — so the smaller page costs one more call rather than any data.

Known limitations

Upstream ignores its own fields= partial-response parameter, so every byte is fetched before being projected away. Projection saves the agent's context, not the network.
total_results is an estimate over a live index. It drifts between calls seconds apart.
place_type and admin_level have no published code table. The raw integers are relayed and display_name carries the meaning.
A place crossing the antimeridian has a degenerate bounding box upstream. It is relayed as computed, not repaired.
Obscured coordinates cannot be resolved, by design. A threatened-taxon record reports a locality with an accuracy radius in the tens of kilometres.
A section named in inaturalist_get_taxon comes back whole however large it is — truncating a section the caller asked for by name is the failure the outline exists to prevent.
The daily request counter is per process. A restart resets it, and two processes behind one egress IP do not share it. Every caller of the public hosted instance draws on that one process's budget.
inaturalist_get_leaderboard can address only the top 500 entries, against the 10,000-result window on observation search.

Getting started

Public Hosted Instance

A public instance is available at https://inaturalist.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

json

{
  "mcpServers": {
    "inaturalist-mcp-server": {
      "type": "streamable-http",
      "url": "https://inaturalist.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

Add the following to your MCP client configuration file.

json

{
  "mcpServers": {
    "inaturalist-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/inaturalist-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

json

{
  "mcpServers": {
    "inaturalist-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/inaturalist-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with Docker:

json

{
  "mcpServers": {
    "inaturalist-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/inaturalist-mcp-server:latest"]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

Bun v1.4.0 or higher (or Node.js ≥ 24.0.0).
No API key required — the iNaturalist v1 API is keyless, and this server never authenticates.
The published terms ask clients to identify themselves. A descriptive User-Agent with a contact URL is sent by default; keep one in any INATURALIST_USER_AGENT override.

Installation

Clone the repository:

git clone https://github.com/cyanheads/inaturalist-mcp-server.git

Navigate into the directory:

cd inaturalist-mcp-server

Install dependencies:

bun install

Configure environment (optional):

cp .env.example .env
# edit .env to override defaults — no required vars

Configuration

Variable	Description	Default
`MCP_TRANSPORT_TYPE`	Transport: `stdio` or `http`	`stdio`
`MCP_HTTP_PORT`	HTTP server port	`3010`
`MCP_HTTP_ENDPOINT_PATH`	HTTP endpoint path where the MCP server is mounted	`/mcp`
`MCP_SESSION_MODE`	HTTP session posture: `stateless`, `stateful`, or `auto`. Overrides the `stateless` declared in `src/index.ts`.	`stateless`
`MCP_PUBLIC_URL`	Public origin override for TLS-terminating reverse-proxy deployments	none
`MCP_AUTH_MODE`	Authentication: `none`, `jwt`, or `oauth`	`none`
`MCP_LOG_LEVEL`	Log level (`debug`, `info`, `notice`, `warning`, `error`)	`info`
`MCP_GC_PRESSURE_INTERVAL_MS`	Opt-in Bun-only forced-GC pressure loop (ms). Recommended starting point if heap growth is observed: `60000`.	`0` (disabled)
`LOGS_DIR`	Directory for log files (Node.js only)	`<project-root>/logs`
`STORAGE_PROVIDER_TYPE`	Storage backend: `in-memory`, `filesystem`, `supabase`, `cloudflare-kv/r2/d1`. Backs the response cache.	`in-memory`
`INATURALIST_USER_AGENT`	`User-Agent` sent on every request to `api.inaturalist.org`. Keep a contact URL in any override.	`inaturalist-mcp-server/<version> (+<repo url>)`
`INATURALIST_MIN_REQUEST_INTERVAL_MS`	Minimum spacing between outbound request starts, in milliseconds.	`1100`
`INATURALIST_MAX_CONCURRENT_REQUESTS`	Maximum outbound requests in flight.	`4`
`INATURALIST_DAILY_REQUEST_BUDGET`	Outbound requests allowed per UTC day, counted in-process.	`9000`
`OTEL_ENABLED`	Enable OpenTelemetry	`false`

See .env.example for the full list of optional overrides.

Running the server

Local development

Build and run the production version:

# One-time build
bun run rebuild

# Run the built server
bun run start:stdio
# or
bun run start:http

Run checks and tests:

bun run devcheck  # Lint, format, typecheck, security
bun run test      # Vitest test suite
bun run lint:mcp  # Validate MCP definitions against spec

Docker

docker build -t inaturalist-mcp-server .
docker run --rm -p 3010:3010 inaturalist-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/inaturalist-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Directory	Purpose
`src/index.ts`	`createApp()` entry point — registers tools and resources, inits the service.
`src/config`	Server-specific environment variable parsing and validation with Zod.
`src/mcp-server/tools`	Tool definitions (`*.tool.ts`) plus the shared filter, record, and taxon-document helpers.
`src/mcp-server/resources`	Resource definitions (`*.resource.ts`) — taxon and observation.
`src/services/inaturalist`	iNaturalist service layer — allowlisted client, pacer, cache, and response projections.
`tests/`	Unit and integration tests mirroring the `src/` structure.

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

Handlers throw, framework catches — no try/catch in tool logic
Use ctx.log for logging, ctx.state for storage
Register new tools and resources in the createApp() arrays
Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.

Install

Tools (10)

inaturalist_list_referenceinaturalist_resolve_nameinaturalist_find_placesinaturalist_search_observationsinaturalist_get_observationinaturalist_get_species_countsinaturalist_get_histograminaturalist_get_leaderboard

Configuration

Environment variables

MCP_LOG_LEVELdefault info

Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

INATURALIST_USER_AGENT

User-Agent sent on every request to api.inaturalist.org. Defaults to the package name, its version, and the repository URL. Keep a contact URL in any override — the published terms ask for identifiable clients.

INATURALIST_MIN_REQUEST_INTERVAL_MSdefault 1100

Minimum spacing between outbound request starts, in milliseconds. The default holds the sustained rate near 54 requests per minute, under the 60 the upstream asks for and well under its 100 ceiling.

INATURALIST_MAX_CONCURRENT_REQUESTSdefault 4

Maximum outbound requests in flight. Separate from the start interval: spacing bounds the sustained rate, this bounds the burst so one slow call does not stall the lane.

INATURALIST_DAILY_REQUEST_BUDGETdefault 9000

Outbound requests allowed per UTC day, counted in-process. The default sits under the 10,000 per day the upstream asks for, and exhaustion fails loudly rather than degrading silently. The counter is per process and resets on restart.

MCP_TRANSPORT_TYPEdefault http

Selects the HTTP transport.

MCP_HTTP_HOSTdefault 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault /mcp

The endpoint path for the MCP server.

MCP_AUTH_MODEdefault none

Authentication mode to use: 'none', 'jwt', or 'oauth'.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "inaturalist-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@cyanheads/inaturalist-mcp-server@0.2.2"
      ],
      "env": {
        "MCP_LOG_LEVEL": "info",
        "INATURALIST_USER_AGENT": "<YOUR_INATURALIST_USER_AGENT>",
        "INATURALIST_MIN_REQUEST_INTERVAL_MS": "1100",
        "INATURALIST_MAX_CONCURRENT_REQUESTS": "4",
        "INATURALIST_DAILY_REQUEST_BUDGET": "9000"
      }
    }
  }
}

iaturalist-mcp-server (io.github.cyanheads/inaturalist-mcp-server)

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

inaturalist_list_reference

inaturalist_resolve_name

inaturalist_find_places

inaturalist_search_observations

inaturalist_get_observation

inaturalist_get_species_counts

inaturalist_get_histogram

inaturalist_get_leaderboard

inaturalist_get_similar_species

inaturalist_get_taxon

@cyanheads/inaturalist-mcp-server

Overview

Tools

Resources

Capability reference

inaturalist_list_reference tool

inaturalist_resolve_name tool

inaturalist_find_places tool

inaturalist_search_observations tool

inaturalist_get_observation tool

inaturalist_get_species_counts tool

inaturalist_get_histogram tool

inaturalist_get_leaderboard tool

inaturalist_get_similar_species tool

inaturalist_get_taxon tool

inaturalist://taxa/{taxon_id} resource

inaturalist://observations/{observation_id} resource

Features

Licensing and attribution

Rate limits and response size

Known limitations

Getting started

Public Hosted Instance

Self-Hosted / Local

Prerequisites

Installation

Configuration

Running the server

Local development

Docker

Project structure

Development guide

Contributing

License

Install

Configuration

Related servers

`inaturalist_list_reference` _tool

`inaturalist_resolve_name` _tool

`inaturalist_find_places` _tool

`inaturalist_search_observations` _tool

`inaturalist_get_observation` _tool

`inaturalist_get_species_counts` _tool

`inaturalist_get_histogram` _tool

`inaturalist_get_leaderboard` _tool

`inaturalist_get_similar_species` _tool

`inaturalist_get_taxon` _tool

`inaturalist://taxa/{taxon_id}` _resource

`inaturalist://observations/{observation_id}` _resource