io.github.cyanheadsPublished by GitHub account cyanheadsv0.3.2Updated Nov 1, 2026
Search iNaturalist sightings, identification threads, phenology, and look-alike species.
Read-only, keyless access to iNaturalist: search wildlife sightings, read identification threads, chart phenology, and find look-alike taxa.
Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.
Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.
Read https://sourceweft.com/mcp/io.github.cyanheads%2Finaturalist-mcp-server/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.Add this to your client's mcpServers config.
{
"mcpServers": {
"inaturalist": {
"type": "http",
"url": "https://inaturalist.caseyjhand.com/mcp"
}
}
}Search wildlife sightings, read identification threads, rank taxa by area, chart phenology, and find look-alike taxa from iNaturalist via MCP. STDIO or Streamable HTTP.
Public Hosted Server: https://inaturalist.caseyjhand.com/mcp
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 taxa of an area; and explore related taxa through shared identification evidence. No API key required.
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.
inaturalist_list_reference tooltopic 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 countssource 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 attributesinaturalist_resolve_name toolq plus type: taxon (default; word-start name matching or exact numeric ID, with optional rank) or place / project / user / any (scored cross-kind search with limited spelling tolerance); applied limit up to 30, default 10page for relevance-ranked suggestions. Explicit taxon name pages browse ascending taxon IDs from page 1; their multilingual match population can differ from autocomplete. Keep the limit fixed; page × applied limit must stay within 10,000. Numeric taxon IDs have one pagekind and id, plus login on users. A true miss returns found: false with guidance; an empty page beyond matching records retains found: true. Every reply discloses totalCount, truncated, shown, and capinaturalist_find_places toolq (display-name prefix or analyzed words) or all four of nelat, nelng, swlat, swlng, otherwise invalid_geography; per_page is forwarded on both arms, default 10, served maximum 20 per list. Strict mode accepts up to 30, then applies the same served ceilingq 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 strippedcap is the applied size for names and twice that size for a box's two lists, including empty repliesinaturalist_search_observations tooltaxon_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_filterslicense / photo_license take the seven CC codes, OR-joined; photo_license matches any photo under the code, independent of the record's own license_codedeferred observation IDs identify the suffix; fetch them with inaturalist_get_observation and the same include before following the upstream page continuationacc_below accepts positive fractional metres up to 2,147,483,647 and selects measured accuracy strictly below the threshold, excluding missing accuracy. obscuration accepts obscured, private, and none; it checks both observer and taxon geoprivacy, with none requiring both to be open/unset. month accepts observed calendar months 1–12created_d1/created_d2 independently bound upload dates; updated_since accepts a calendar date or ISO datetime with timezone. identifications selects most_agree, some_agree, or most_disagree. Search, by-id records, and observation resources preserve nullable created_at and updated_at stringsinaturalist_get_observation toolobservation_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 availableobservations 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 ceilingmax(4, floor(40 / records returned)) entries per array and reports *_total beside *_showninaturalist_get_species_counts tooltotal_results counts taxa, and the species field retains its upstream name.introduced, native, threatened, endemic, csi, hrank/lrank, and observed month (integer array, 1–12) are shared with search. rank selects one exact rank; equal rank-band bounds select a level, including both species and hybrid at level 10. Conservation codes match global listings plus listings at exactly place_id, excluding ancestor-place listings. Status flags describe the observation's indexed taxon at its location.per_page up to 50, default 25, with page offsetposition (absolute, counted from page 1), taxon_id, and observation_count; truncationCeiling is the last count shown, which nothing off the page exceedsinaturalist_get_histogram toolinterval: 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 curvetruncated / shown / cap. total sums every upstream bucket in the histogram window, including omitted rows; it is not an all-time taxon count. The row cap is no byte guaranteed1/d2 bound observation dates; created_d1/created_d2 separately bound upload dates. date_field selects which date is bucketed without changing either filter pairapplied_filters.window_start discloses that effective start; no upper bound is added. Seasonal intervals have no generated startuser_id or user_login selects an observer's sightings; project_id selects a project. Resolve either with inaturalist_resolve_name; an observer ID and login are mutually exclusiveinaturalist_get_leaderboard toolkind: observers or identifiers, with one area form, taxon_id, d1/d2, and quality_grade; applied per_page up to 250, default 25page × per_page past 500 fails as leaderboard_window_exceeded; entries carry rank, login, and count (measured per count_metric), plus species_count for observerstruncated: false when the matching set is exhausteduser_id or user_login and project_id scope the underlying observations. On observers, an observer selector returns that observer's own row; on identifiers, it returns people who identified that observer's sightings. It does not select identifications authored by the named observerinaturalist_get_similar_species tooltaxon_id at genus or finer, otherwise taxon_rank_too_coarse; an optional area, d1/d2, quality_grade, and captive scope the evidence; default limit 20, served maximum 24. Strict mode accepts up to 50, then applies the same served ceilingmisidentification_count counts observations carrying current, non-hidden identifications of both taxa, including ancestor taxa. This is symmetric co-identification evidence, not directional corrections or visual similarity. truncationCeiling describes a locally cut ranking; upstream may omit further taxa and offers no paginationinaturalist_get_taxon tooltaxon_id; sections selects from summary, taxonomy, children, conservation, photos, encyclopedia, and an unknown name fails as unknown_sectionkind: "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 severalinaturalist://taxa/{taxon_id} resourceapplication/json; a resource read can't name sections, so use inaturalist_get_taxon for the outline pathtaxon_id comes from inaturalist_resolve_name; cached for six hoursinaturalist://observations/{observation_id} resourceapplication/json with its first 40 identifications and first 40 filled observation fields, each with its _total beside its _shownobservation_id comes from inaturalist_search_observations; cached for fifteen minutesBuilt 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:
fields= parameter, so every response is projected in-process (a common taxon record arrives at 95 KB)place_id, lat+lng+radius in kilometres (clamped at 20,040 by default; 500 maximum in strict mode), or a four-corner box. The geographic filter is retained at the ceiling. Partial or mixed forms fail as invalid_geography, and d1 after d2 as inverted_date_rangeterm_value_id, an impossible date, an unknown licence coderate_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 notlicense_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 onlyAgent-friendly output:
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 onlyinaturalist_list_reference for vocabularies, since an unrecognised value returns nothing); a page past the end names the last page with resultstruncated, shown, and cap, plus truncationCeiling on descending rankingsinclude: [] retains its explicit expansion selectionplace_id returns typed unknown_place_id guidance to resolve it with inaturalist_find_placesA public instance is available at https://inaturalist.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:
Add the following to your MCP client configuration file.
Or with npx (no Bun required):
Or with Docker:
For Streamable HTTP, set the transport and start the server:
User-Agent with a contact URL is sent by default; keep one in any INATURALIST_USER_AGENT override.See .env.example for the full list of optional overrides.
Build and run the production version:
Run checks and tests:
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.
See CLAUDE.md for development guidelines and architectural rules. The short version:
try/catch in tool logicctx.log for logging, ctx.state for storagecreateApp() arrays in src/index.tsIssues are welcome. Run checks and tests before submitting:
This project is licensed under the Apache 2.0 License. See the LICENSE file for details.
Source: README.md at commit f975dca
Inaturalist List Reference
Look up annotation attributes/values, quality grades, licences, ranks, iconic taxa, and conservation codes before filtering; unknown values can silently return nothing. Conservation codes are the normalised csi filter, distinct from authority-specific taxon status text. With topic controlled_terms and taxon_id, also return observed annotation usage and counts.
topicrequiredtaxon_idInaturalist Resolve Name
Resolve organism, place, project, or observer names to identifiers. Taxon lookup matches word starts within a name, not only its beginning; other types use cross-kind search with limited spelling tolerance. Without page, candidates retain relevance order. Explicit taxon pages browse name matches in ascending taxon-ID order; this can differ from autocomplete matching across languages. A miss returns found false with recovery guidance.
qrequiredpageranktypelimitInaturalist Find Places
Resolve a place name to a place id, or list places covering a map area. Pass q to match a display-name prefix or all analyzed query terms within it, or all four of nelat, nelng, swlat and swlng for a map area — exactly one of the two, never both. Each result carries its bounding box, place type, and containment chain. Upstream serves at most 20 places per list and may omit more.
qnelatnelngswlatswlngper_pageInaturalist 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.
qd1d2csilatlngpagehranklrankmonthnelatnelng+34 moreInaturalist Get Observation
Fetch up to 10 distinct 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 attempted batch costs one upstream request. Records come back in requested order; remaining distinct ids are deferred for another call with the same include. Missing attempted ids appear in unresolved; the call fails only when nothing resolved and no deferred work remains. Long threads and observation-field lists share a response budget across resolved records — up to 40 entries per array for one record, 4 for a full batch — and every record reports the size of each array beside what it kept.
includeobservation_idrequiredInaturalist Get Species Counts
Rank leaf taxa recorded in an area and period, most-observed first. Includes hybrids and coarser identifications; subspecies roll up to their species. 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 taxa, use inaturalist_get_leaderboard.
d1d2csilatlngpagerankhranklrankmonthnelatnelng+18 moreInaturalist 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; absolute intervals (year, month, week, day, hour) bucket real dates and disclose their window start. 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.
d1d2latlngnelatnelngswlatswlngradiuscaptiveterm_iduser_id+11 moreInaturalist 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.
d1d2latlngkindrequiredpagenelatnelngswlatswlngradiususer_id+6 moreInaturalist Get Similar Species
List related taxa ranked by observations carrying current identifications of both taxa. This is co-identification evidence, not a directional correction count or an exhaustive list of visually similar organisms. Scope it to an area in exactly one form (place_id, the lat/lng/radius triple in kilometres, or a four-corner bounding box), or leave the area off for global results. The taxon must be a genus or finer (genus, species, or below). Resolve the organism name to a taxon id with inaturalist_resolve_name first.
d1d2latlnglimitnelatnelngswlatswlngradiuscaptiveplace_id+2 moreInaturalist 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.
sectionstaxon_idrequired100% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
{ "mcpServers": { "inaturalist-mcp-server": { "type": "streamable-http", "url": "https://inaturalist.caseyjhand.com/mcp" } }}{ "mcpServers": { "inaturalist-mcp-server": { "type": "stdio", "command": "bunx", "args": ["@cyanheads/inaturalist-mcp-server@latest"], "env": { "MCP_TRANSPORT_TYPE": "stdio", "MCP_LOG_LEVEL": "info" } } }}{ "mcpServers": { "inaturalist-mcp-server": { "type": "stdio", "command": "npx", "args": ["-y", "@cyanheads/inaturalist-mcp-server@latest"], "env": { "MCP_TRANSPORT_TYPE": "stdio", "MCP_LOG_LEVEL": "info" } } }}{ "mcpServers": { "inaturalist-mcp-server": { "type": "stdio", "command": "docker", "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/inaturalist-mcp-server:latest"] } }}MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http# Server listens at http://localhost:3010/mcpgit clone https://github.com/cyanheads/inaturalist-mcp-server.gitcd inaturalist-mcp-serverbun installcp .env.example .env# edit .env to override defaults — no required vars# One-time buildbun run rebuild
# Run the built serverbun run start:stdio# orbun run start:httpbun run devcheck # Lint, format, typecheck, securitybun run test # Vitest test suitebun run lint:mcp # Validate MCP definitions against specdocker build -t inaturalist-mcp-server .docker run --rm -p 3010:3010 inaturalist-mcp-serverbun run devcheckbun run test