@cyanheads/inaturalist-mcp-server

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

Overview

iNaturalist's index of 387M+ georeferenced citizen-science observations of plants, animals, and fungi. Search sightings by area, date, taxon, and annotation; read the identification thread behind a record; chart when a taxon appears; rank the species of an area; and check what a look-alike is most often confused with. No API key required.

Tools

Resources

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

The published inaturalist-guide covers identifier provenance, matched cohorts, annotations, and evidence coverage across calls. It ships with npm, plugin, MCPB, and Docker installs; clients supporting MCP skill discovery can retrieve it directly. The SDK also exposes skill resources alongside the two domain resources.

Related MCP server: musicbrainz-mcp-server

Capability reference

inaturalist_list_reference tool

• topic picks one table: controlled_terms (fetched live), quality_grades, licenses, ranks, iconic_taxa, or conservation_status_codes; taxon_id, valid only with controlled_terms, adds observed_usage, the annotation pairs recorded for that taxon with counts

• source is upstream or static; annotation attributes and their values carry numeric ids to pass as term_id and term_value_id, since labels repeat across attributes

inaturalist_resolve_name tool

• q plus type: taxon (default; name-prefix autocomplete, so "monarch" hits where "monarch butterfly" misses, with an optional rank) or place / project / user / any (scored cross-kind search); applied limit up to 30, default 10

• Each candidate carries kind and id, plus login on users; a miss returns found: false with guidance instead of an error

inaturalist_find_places tool

• Exactly one of q (place-name prefix) or all four of nelat, nelng, swlat, swlng, otherwise invalid_geography; applied per_page up to 30 (default 10) applies to the box arm only, per list

• q returns places[], a box returns standard[] and community[]; each place carries id, bbox, ancestor_place_ids, place_type, admin_level, and location, with boundary polygons stripped

inaturalist_search_observations tool

• One area form plus 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, and q+search_on; applied per_page up to 25, default 10; optional sounds filters for audio-bearing records, while include expands photos, annotations, sounds (identification threads live on inaturalist_get_observation)

• page walks the first 10,000 results; past that, order by id descending and pass each page's next_cursor as cursor. Returns total_results (a live estimate) and has_more, and echoes applied_filters

• license / photo_license take the seven CC codes, OR-joined; photo_license matches any photo under the code, independent of the record's own license_code

• The complete serialized reply stays within 50,000 UTF-8 bytes by returning a prefix of whole records. Ordered deferred observation IDs identify the suffix; fetch them with inaturalist_get_observation and the same include before following the upstream page continuation

inaturalist_get_observation tool

• Submit 1–100 observation_ids: duplicates are removed in first-seen order, the first ten distinct IDs are attempted in one upstream request, and the rest return in deferred; with limit clamping disabled, at most ten submitted IDs are accepted. include defaults to ["identifications"], with comments, photos, annotations, and sounds available

• Resolved records come back in observations in request order, attempted misses in unresolved; fails as not_found only when none resolve and nothing is deferred. Adds community_taxon, description, and filled observation_fields; strings remain complete, so detail replies have no universal byte ceiling

• Identifications, comments, and observation fields share a 40-entry budget: each record keeps max(4, floor(40 / records returned)) entries per array and reports *_total beside *_shown

inaturalist_get_species_counts tool

• One area form plus the search filters for taxon, dates, quality grade, captive, annotations, iconic taxa, observer, and project; applied per_page up to 50, default 25, with page offset

• Rows carry position (absolute, counted from page 1), taxon_id, and observation_count; truncationCeiling is the last count shown, which nothing off the page exceeds

inaturalist_get_histogram tool

• interval: month_of_year (default) or week_of_year for a seasonal curve, or year / month / week / day / hour for absolute dates; date_field observed (default) or created; taxon_id optional, and an annotation pair (Life Stage 1 = Larva 6) or iconic_taxa narrows the curve

• Returns every bucket in order, zeros included, plus a total across all of them; capped at 800 buckets from the start of the range, with truncated / shown / cap

• d1/d2 bound observation dates; created_d1/created_d2 separately bound upload dates. date_field selects which date is bucketed without changing either filter pair

inaturalist_get_leaderboard tool

• kind: observers or identifiers, with one area form, taxon_id, d1/d2, and quality_grade; applied per_page up to 250, default 25

• Only the top 500 are addressable, so page × per_page past 500 fails as leaderboard_window_exceeded; entries carry rank, login, and count (measured per count_metric), plus species_count for observers

• A full final page reports truncated: false when the matching set is exhausted

inaturalist_get_similar_species tool

• taxon_id at genus or finer, otherwise taxon_rank_too_coarse; an optional area, d1/d2, quality_grade, and captive scope the set to a region; applied limit up to 50, default 20

• Ranked by misidentification_count, with truncationCeiling when the limit cuts the set

inaturalist_get_taxon tool

• One taxon_id; sections selects from summary, taxonomy, children, conservation, photos, encyclopedia, and an unknown name fails as unknown_section

• kind: "full" carries the profile; kind: "outline" lists each section with its byte size when the profile overflows. A named section always comes back whole, so sum the outline's sizes before asking for several

inaturalist://taxa/{taxon_id} resource

• The whole projected taxon document as application/json; a resource read can't name sections, so use inaturalist_get_taxon for the outline path

• taxon_id comes from inaturalist_resolve_name; cached for six hours

inaturalist://observations/{observation_id} resource

• One observation as application/json with its first 40 identifications and first 40 filled observation fields, each with its _total beside its _shown

• observation_id comes from inaturalist_search_observations; cached for fifteen minutes

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 coverage of the iNaturalist v1 API. Upstream ignores its own fields= parameter, so every response is projected in-process (a common taxon record arrives at 95 KB)

• Area-scoped tools take one area form: place_id, lat+lng+radius in kilometres (up to 500), or a four-corner box. Partial or mixed forms fail as invalid_geography, and d1 after d2 as inverted_date_range

• Per-endpoint parameter allowlist, plus in-process rejection of input upstream would silently widen or zero out: a lone term_value_id, an impossible date, an unknown licence code

• Self-paced traffic: spaced request starts, capped concurrency, and a per-UTC-day budget that fails as rate_budget_exhausted. The counter is per process, so every caller of the hosted instance shares it. Taxa, places, controlled terms, histograms, and look-alike sets are cached; observation queries are not

• Licences relayed verbatim: a null license_code means all rights reserved, photo attribution must travel with the image, and photos are linked, never proxied. An obscured coordinate is a locality, and observers are identified by login only

Agent-friendly output:

• Applied defaults echoed: search, species counts, histograms, and leaderboards return applied_filters (research-grade and wild-only by default, plus any ordering a cursor forced). captive: true selects captive or cultivated records only; false selects wild records only

• Zero-hit notices name the filter most likely responsible and the tool that decodes it (inaturalist_list_reference for vocabularies, since an unrecognised value returns nothing); a page past the end names the last page with results

• Truncation disclosed on every path: truncated, shown, and cap, plus truncationCeiling on descending rankings

• Empty filter arrays are ignored with a notice; nonempty annotation values still require a nonempty attribute array. include: [] retains its explicit expansion selection

• An unknown place_id returns typed unknown_place_id guidance to resolve it with inaturalist_find_places

• Upstream free text renders as literal quoted content, preserving line separators, HTML, entities, and complete strings after CommonMark parsing. NUL-containing strings use a labeled JSON string literal; URL fields render as links. Present empty expansions, zero counts, and null or empty descriptions remain visible

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:

{
  "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.

{
  "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):

{
  "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:

{
  "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 v24+).

• No API key: the iNaturalist v1 API is keyless. The published terms ask clients to identify themselves, so a User-Agent with a contact URL is sent by default; keep one in any INATURALIST_USER_AGENT override.

Installation

1. Clone the repository:

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

2. Navigate into the directory:

cd inaturalist-mcp-server

3. Install dependencies:

bun install

4. Configure environment (optional):

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

Configuration

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

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 in src/index.ts

• 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.