@cyanheads/inaturalist-mcp-server
This server has a remotely hosted endpoint. Open its connector listing for connection details, authentication requirements, and setup instructions:
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 taxa of an area; and explore related taxa through shared identification evidence. No API key required.
Tools
Tool | Description |
| Decode the controlled vocabularies the other tools filter on: annotation attributes and values, quality grades, licences, ranks, iconic taxa, conservation-status codes |
| Resolve a common or scientific name to a taxon id, or a place, project, or observer name to its id, as ranked candidates |
| Resolve a place name to a place id, or list the places covering a map area, each with its bounding box and containment chain |
| Search georeferenced sightings by area, date, taxon, quality grade, annotation, conservation status, observer, project, and licence |
| Fetch up to 10 observations by id with their community identification thread and consensus taxon |
| Rank the leaf taxa recorded in an area and period, most-observed first, optionally for one observer or project |
| Build a phenology histogram for a taxon in an area: which months, weeks, or years it is recorded in |
| Rank the most active observers or identifiers for an area, period, and taxon |
| Rank related taxa by observations carrying identifications of both taxa, for a genus-or-finer taxon |
| Fetch a taxon profile: taxonomic path, conservation listings by authority, encyclopedia summary, photos, and children |
Resources
Resource | Description |
| Taxon profile by numeric taxon id, as injectable context |
| One observation with its identification thread expanded, as injectable context |
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
topicpicks one table:controlled_terms(fetched live),quality_grades,licenses,ranks,iconic_taxa, orconservation_status_codes(theiucnlevels listings carry, all butNEandDDvalid ascsi);taxon_id, valid only withcontrolled_terms, addsobserved_usage, the annotation pairs recorded for that taxon with countssourceisupstreamorstatic; annotation attributes and their values carry numeric ids to pass asterm_idandterm_value_id, since labels repeat across attributes
inaturalist_resolve_name tool
qplustype:taxon(default; word-start name matching or exact numeric ID, with optionalrank) orplace/project/user/any(scored cross-kind search with limited spelling tolerance); appliedlimitup to 30, default 10Omit
pagefor 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 limitmust stay within 10,000. Numeric taxon IDs have one pageEach candidate carries
kindandid, plusloginon users, andis_activeon taxa withcurrent_synonymous_taxon_idswhen the taxon is inactive. A true miss returnsfound: falsewithguidance; an empty page beyond matching records retainsfound: true. Every reply disclosestotalCount,truncated,shown, andcap
inaturalist_find_places tool
Exactly one of
q(display-name prefix or analyzed words) or all four ofnelat,nelng,swlat,swlng, otherwiseinvalid_geography;per_pageis forwarded on both arms, default 10, served maximum 20 per list. Strict mode accepts up to 30, then applies the same served ceilingqreturnsplaces[], a box returnsstandard[]andcommunity[]; each place carriesid,bbox,ancestor_place_ids,place_type,admin_level, andlocation, with boundary polygons strippedName autocomplete has no pagination; narrow the text or use a smaller map area to explore further matches.
capis the applied size for names and twice that size for a box's two lists, including empty replies
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_idoruser_login,ident_user_id,unobserved_by_user_id,project_id, andq+search_on; appliedper_pageup to 25, default 10; optionalsoundsfilters for audio-bearing records, whileincludeexpandsphotos,annotations,sounds(identification threads live oninaturalist_get_observation)pagewalks the first 10,000 results; past that, order byiddescending and pass each page'snext_cursorascursor. Returnstotal_results(a live estimate) andhas_more, and echoesapplied_filterslicense/photo_licensetake the seven CC codes, OR-joined;photo_licensematches any photo under the code, independent of the record's ownlicense_codeThe complete serialized reply stays within 50,000 UTF-8 bytes by returning a prefix of whole records. Ordered
deferredobservation IDs identify the suffix; fetch them withinaturalist_get_observationand the sameincludebefore following the upstream page continuation. Every record carriesoutlinks, e.g. its GBIF occurrence for citation, counted inside the byte budgetacc_belowaccepts positive fractional metres up to 2,147,483,647 and selects measured accuracy strictly below the threshold, excluding missing accuracy.obscurationacceptsobscured,private, andnone; it checks both observer and taxon geoprivacy, withnonerequiring both to be open/unset.monthaccepts observed calendar months 1–12created_d1/created_d2independently bound upload dates;updated_sinceaccepts a calendar date or ISO datetime with timezone.identificationsselectsmost_agree,some_agree, ormost_disagree. Search, by-id records, and observation resources preserve nullablecreated_atandupdated_atstrings
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 indeferred; with limit clamping disabled, at most ten submitted IDs are accepted.includedefaults to["identifications"], withcomments,photos,annotations, andsoundsavailableResolved records come back in
observationsin request order, attempted misses inunresolved; fails asnot_foundonly when none resolve and nothing is deferred. Addscommunity_taxon,description, and filledobservation_fields(each withdatatype, and the five-fieldtaxonwhen upstream resolved a taxon-type value); strings remain complete, so detail replies have no universal byte ceilingIdentifications, comments, and observation fields are sorted by ascending id and share the
array_limitbudget (default 40, ceiling 1,500): each record keepsmin(array_limit, max(4, floor(array_limit / records returned)))entries per array fromarray_offsetand reports*_totalbeside*_shown;next_array_offsetcontinues every array with the same ids andinclude; each identification and comment relays upstream'shiddenflag, andidentifications_hidden/comments_hiddencount hidden entries over the whole array, the same on every page
inaturalist_get_species_counts tool
Counts leaf taxa, including hybrids and coarser identifications; subspecies roll up to their species.
total_resultscounts taxa, and thespeciesfield retains its upstream name.introduced,native,threatened,endemic,csi,hrank/lrank, and observedmonth(integer array, 1–12) are shared with search.rankselects 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 exactlyplace_id, excluding ancestor-place listings. Status flags describe the observation's indexed taxon at its location.One area form plus the search filters for taxon, dates, quality grade, captive, annotations, iconic taxa, observer,
ident_user_id(records a user identified, their own observations included),unobserved_by_user_id(taxa a user has never observed), and project; appliedper_pageup to 50, default 25, withpageoffsetRows carry
position(absolute, counted from page 1),taxon_id, andobservation_count;truncationCeilingis the last count shown, which nothing off the page exceeds
inaturalist_get_histogram tool
interval:month_of_year(default) orweek_of_yearfor a seasonal curve, oryear/month/week/day/hourfor absolute dates;date_fieldobserved(default) orcreated;taxon_idoptional, and an annotation pair (Life Stage1= Larva6) oriconic_taxanarrows the curveReturns up to 25,000 buckets in order, zeros included, with
truncated/shown/cap.totalsums 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/d2bound observation dates;created_d1/created_d2separately bound upload dates.date_fieldselects which date is bucketed without changing either filter pairAbsolute intervals supply only the selected family's missing lower bound, anchored to its upper bound or today UTC: year/month subtract 100 calendar years, week 10 years, day one year, hour seven days.
applied_filters.window_startdiscloses that effective start; no upper bound is added. Seasonal intervals have no generated startOn truncation, follow the first-omitted-bucket guidance with other filters and upper bounds retained. Date-only continuation can overlap earlier or partial boundary buckets: deduplicate keys, preserve earlier counts, and never add or replace repeated counts. This cannot reconstruct complete boundary-bucket totals
user_idoruser_loginselects an observer's sightings;project_idselects a project. Resolve either withinaturalist_resolve_name; an observer ID and login are mutually exclusive
inaturalist_get_leaderboard tool
kind:observersoridentifiers, with one area form,taxon_id,d1/d2, andquality_grade; appliedper_pageup to 250, default 25Only the top 500 are addressable, so
page × per_pagepast 500 fails asleaderboard_window_exceeded; entries carryrank,login, andcount(measured percount_metric), plusspecies_countfor observersA full final page reports
truncated: falsewhen the matching set is exhausteduser_idoruser_loginandproject_idscope 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 observer
inaturalist_get_similar_species tool
taxon_idat genus or finer, otherwisetaxon_rank_too_coarse; an optional area,d1/d2,quality_grade, andcaptivescope the evidence; defaultlimit20, served maximum 24. Strict mode accepts up to 50, then applies the same served ceilingThe retained
misidentification_countcounts observations carrying current, non-hidden identifications of both taxa, including ancestor taxa. This is symmetric co-identification evidence, not directional corrections or visual similarity.truncationCeilingdescribes a locally cut ranking; upstream may omit further taxa and offers no pagination
inaturalist_get_taxon tool
One
taxon_id; an inactive taxon carries its successor ids incurrent_synonymous_taxon_ids, and each conservation listing carriesiucnwith itsiucn_code;sectionsselects fromsummary,taxonomy,children,conservation,photos,encyclopedia, and an unknown name fails asunknown_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 several
inaturalist://taxa/{taxon_id} resource
The whole projected taxon document as
application/json; a resource read can't name sections, so useinaturalist_get_taxonfor the outline pathtaxon_idcomes frominaturalist_resolve_name; cached for six hours
inaturalist://observations/{observation_id} resource
One observation as
application/jsonwith its first 40 identifications and first 40 filled observation fields by ascending id, each with its_totalbeside its_shown, plusidentifications_hiddenand the record'soutlinks; page the rest withinaturalist_get_observationarray_offsetobservation_idcomes frominaturalist_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+radiusin 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 asinvalid_geography, andd1afterd2asinverted_date_rangePer-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 codeSelf-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 notLicences relayed verbatim: a null
license_codemeans all rights reserved, photoattributionmust travel with the image, and photos are linked, never proxied. Anobscuredcoordinate is a locality, and observers are identified byloginonly
Agent-friendly output:
Applied defaults echoed: search, species counts, and histograms return
applied_filters(research-grade and wild-only by default, plus any ordering a cursor forced); leaderboards echoquality_gradealone, take nocaptive, and count captive records too.captive: trueselects captive or cultivated records only;falseselects wild records only. Captive records are graded casual, so pairtruewith"casual"inquality_grade; without it a notice discloses the grade-inconsistent cohortZero-hit notices name the filter most likely responsible and the tool that decodes it (
inaturalist_list_referencefor vocabularies, since an unrecognised value returns nothing); a page past the end names the last page with resultsTruncation disclosed on every path:
truncated,shown, andcap, plustruncationCeilingon descending rankingsEmpty filter arrays are ignored with a notice; nonempty annotation values still require a nonempty attribute array.
include: []retains its explicit expansion selectionAn unknown
place_idreturns typedunknown_place_idguidance to resolve it withinaturalist_find_placesUpstream 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/mcpPrerequisites
Bun v1.4.4 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-Agentwith a contact URL is sent by default; keep one in anyINATURALIST_USER_AGENToverride.
Installation
Clone the repository:
git clone https://github.com/cyanheads/inaturalist-mcp-server.gitNavigate into the directory:
cd inaturalist-mcp-serverInstall dependencies:
bun installConfigure environment (optional):
cp .env.example .env
# edit .env to override defaults — no required varsConfiguration
Variable | Description | Default |
|
|
|
| Minimum gap between outbound request starts, in ms. The default holds the rate near 54 per minute. |
|
| Maximum outbound requests in flight. |
|
| Outbound requests allowed per UTC day, counted in-process and reset on restart. |
|
| Strict boolean. Clamp list limits to 30/20/25/50/24/250 for name resolution, places, search, species counts, similar species, and leaderboards, by-id |
|
| Transport: |
|
| HTTP server port. |
|
| HTTP session mode: |
|
| Authentication: |
|
| Log level ( |
|
| Directory for log files (Node.js only). |
|
| Storage backend for the response cache: |
|
| Enable OpenTelemetry. |
|
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:httpRun 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-serverThe 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 |
|
|
| Server-specific environment variable parsing and validation with Zod. |
| Tool definitions ( |
| Resource definitions ( |
| iNaturalist service layer: allowlisted client, pacer, daily budget, cache, and response projections. |
| Unit, integration, and smoke tests, mirroring the |
Development guide
See CLAUDE.md for development guidelines and architectural rules. The short version:
Handlers throw, framework catches — no
try/catchin tool logicUse
ctx.logfor logging,ctx.statefor storageRegister new tools and resources in the
createApp()arrays insrc/index.tsWrap 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 testLicense
This project is licensed under the Apache 2.0 License. See the LICENSE file for details.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
iNaturalist MCP — citizen-science species observations (free, no auth for read-only)
GBIF MCP — wraps the Global Biodiversity Information Facility API v1 (free, no auth)
Query SEC EDGAR filings, XBRL financials, and company data via MCP. STDIO or Streamable HTTP.
Unofficial MusicBrainz MCP — wraps MusicBrainz Web Service v2 (free, no auth)
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables querying citizen-science species observations from iNaturalist via the Pipeworx MCP gateway. Provides read-only access to species data without authentication.101 npmMIT
- AlicenseNot gradedqualityBmaintenanceSearch artists, releases, recordings, works, and labels; traverse relationships; resolve ISRC/ISWC/barcode; fetch cover art via MCP. STDIO or Streamable HTTP.157 npm2Apache 2.0
- AlicenseNot gradedqualityBmaintenanceLook up Pokémon, moves, abilities, items, natures, and type matchups from PokéAPI v2 via MCP. Supports STDIO or Streamable HTTP.387 npm1Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables querying UNHCR refugee, IDP, stateless populations, asylum decisions, returns, and resettlement statistics via MCP, including staging large datasets for SQL queries. Supports stdio or Streamable HTTP transports.108 npm1Apache 2.0