inaturalist-mcp-server

---

概述

iNaturalist 收录了超过 3.87 亿条带地理坐标的公民科学观测记录，涵盖植物、动物和真菌。按区域、日期、分类群和标注搜索目击记录；阅读记录背后的鉴定讨论串；绘制分类群出现时间图表；排列某个区域的物种；并查看外形相似的物种最常与哪些物种混淆。无需 API 密钥。

工具

工具	描述
inaturalist_list_reference	解码其他工具用于筛选的受控词表：标注属性和值、质量等级、许可、分类等级、标志性分类群、保护状态代码
inaturalist_resolve_name	将俗名或学名解析为分类单元 ID，或将地点、项目或观察者名称解析为对应 ID，并按排名列出候选项
inaturalist_find_places	将地点名称解析为地点 ID，或列出覆盖地图区域的地点，并提供每个地点的边界框和包含链
inaturalist_search_observations	按区域、日期、分类单元、质量等级、标注、保护状态、观察者、项目和许可搜索带地理坐标的观察记录
inaturalist_get_observation	按 ID 获取最多 10 条观察记录，并附上社群鉴定讨论串和共识分类单元
inaturalist_get_species_counts	按记录数量从多到少，排列某区域和时段内记录的不同物种；也可选按某位观察者或项目筛选
inaturalist_get_histogram	为某个分类单元在某区域生成物候直方图，显示记录所在的月份、周或年份
inaturalist_get_leaderboard	按区域、时段和分类单元排列最活跃的观察者或鉴定者
inaturalist_get_similar_species	列出某属或更细分类单元最常被误认成的分类单元，并按纠正次数排序
inaturalist_get_taxon	获取分类单元简介：分类路径、各主管机构的保护名录、百科摘要、照片和子级分类单元

资源

资源	描述
inaturalist://taxa/{taxon_id}	按数字分类单元 ID 获取分类单元简介，作为可注入的上下文
inaturalist://observations/{observation_id}	获取一条观察记录，并展开其鉴定讨论串，作为可注入的上下文

这两个资源提供的数据也可通过 inaturalist_get_taxon 和 inaturalist_get_observation 访问，供不展示 MCP 资源的客户端使用。

已发布的 inaturalist-guide 介绍了标识符来源、匹配队列、标注以及各调用的证据覆盖情况。该指南随 npm、插件、MCPB 和 Docker 安装包一同提供；支持 MCP 技能发现的客户端可以直接获取。SDK 还会在这两个领域资源旁提供技能资源。

功能参考

inaturalist_list_reference _工具

• topic 选择一张表：controlled_terms（实时获取）、quality_grades、licenses、ranks、iconic_taxa 或 conservation_status_codes；仅在 controlled_terms 下有效的 taxon_id 会添加 observed_usage，即该分类单元记录的标注属性值对及其数量
• source 为 upstream 或 static；标注属性及其值带有数字 ID，需作为 term_id 和 term_value_id 传入，因为不同属性可能使用相同标签

---

inaturalist_resolve_name _工具

• q 加上 type：taxon（默认；按名称前缀自动补全，因此可通过“monarch”找到结果，而“monarch butterfly”可能找不到；可选提供 rank），或 place / project / user / any（跨类别的评分搜索）；应用后的 limit 最高为 30，默认值为 10
• 每个候选项都包含 kind 和 id，用户候选项还包含 login；未找到时会返回包含 guidance 的 found: false，而不是错误

---

inaturalist_find_places _工具

• 必须且只能提供 q（地点名称前缀），或全部四个参数 nelat、nelng、swlat、swlng；否则返回 invalid_geography；应用后的 per_page 最高为 30（默认值为 10），且仅适用于地图框查询，每个列表分别计算
• q 会返回 places[]，地图框查询会返回 standard[] 和 community[]；每个地点都包含 id、bbox、ancestor_place_ids、place_type、admin_level 和 location，并会剥除边界多边形

---

inaturalist_search_observations _工具

• 一种区域形式，以及 taxon_id、d1/d2、quality_grade、captive、term_id+term_value_id、iconic_taxa、hrank/lrank、csi、threatened/native/introduced/endemic、user_id 或 user_login、project_id 和 q+search_on；应用后的 per_page 上限为 25，默认值为 10；可选的 sounds 用于筛选带音频的记录，而 include 可扩展返回 photos、annotations、sounds（鉴定讨论串由 inaturalist_get_observation 提供）
• page 可遍历前 10,000 条结果；超过此范围后，按 id 降序排序，并将每页的 next_cursor 作为 cursor 传入。返回 total_results（实时估算值）和 has_more，并回显 applied_filters
• license / photo_license 接受七种 CC 代码，以 OR 连接；photo_license 匹配符合该代码的任意照片，与记录自身的 license_code 无关
• 完整序列化回复的大小不超过 50,000 UTF-8 字节，方法是仅返回完整记录组成的前缀。按顺序排列的 deferred 观测 ID 标识未返回的后缀；在继续获取上游页面前，使用相同的 include 通过 inaturalist_get_observation 获取这些记录

---

inaturalist_get_observation _工具

• 提交 1–100 个 observation_id：重复项会按首次出现的顺序去除，前 10 个不同 ID 会在一个上游请求中尝试，其余 ID 会列在 deferred 中；禁用限制钳制时，最多接受 10 个提交的 ID。include 默认为 ["identifications"]，也可使用 comments、photos、annotations 和 sounds
• 已解析的记录按请求顺序放在 observations 中，尝试但未找到的记录放在 unresolved 中；仅当没有任何记录解析成功且没有延后项时，才会以 not_found 失败。添加 community_taxon、description 和已填充的 observation_fields；字符串保持完整，因此详情回复没有通用的字节上限
• 鉴定、评论和观测字段共用 40 条目的额度：每条记录在每个数组中保留 max(4, floor(40 / records returned)) 个条目，并在 *_shown 旁报告 *_total

---

inaturalist_get_species_counts _工具

• 一种区域形式，以及物种分类群、日期、质量等级、圈养状态、注释、标志性分类群、观察者和项目的搜索筛选条件；应用后的 per_page 上限为 50，默认值为 25，page 用于偏移
• 各行包含 position（从第 1 页起计算的绝对位置）、taxon_id 和 observation_count；truncationCeiling 为显示的最后一个计数，页外记录的计数均不会超过此值

---

inaturalist_get_histogram _工具

• interval：季节曲线可用 month_of_year（默认值）或 week_of_year，绝对日期可用 year / month / week / day / hour；date_field 为 observed（默认值）或 created；taxon_id 为可选项，且注释对（Life Stage 1 = Larva 6）或 iconic_taxa 可缩小曲线范围
• 按顺序返回所有分桶，包括计数为零的分桶，并附带所有分桶的 total；从范围起始处最多返回 800 个分桶，并提供 truncated / shown / cap
• d1/d2 限定观测日期；created_d1/created_d2 单独限定上传日期。date_field 选择用于分桶的日期，但不会更改这两组筛选条件

---

inaturalist_get_leaderboard _工具

• kind：observers 或 identifiers，以及一种区域形式、taxon_id、d1/d2 和 quality_grade；应用后的 per_page 上限为 250，默认值为 25
• 仅可访问前 500 个名次，因此 page × per_page 超过 500 时会以 leaderboard_window_exceeded 失败；条目包含 rank、login 和 count（按 count_metric 计算），观察者条目还包含 species_count
• 匹配结果已耗尽时，最后一页即使已满也会报告 truncated: false

---

inaturalist_get_similar_species _工具

• taxon_id 必须是属或更细的分类单元，否则返回 taxon_rank_too_coarse；可选的区域、d1/d2、quality_grade 和 captive 用于限定范围；应用的 limit 最高为 50，默认为 20
• 按 misidentification_count 排序；当 limit 截断结果集时，会提供 truncationCeiling

---

inaturalist_get_taxon _工具

• 一个 taxon_id；sections 可从 summary、taxonomy、children、conservation、photos 和 encyclopedia 中选择；未知名称会返回 unknown_section
• kind: "full" 包含完整档案；当档案超出限制时，kind: "outline" 会列出各部分及其字节大小。指定的部分始终会完整返回，因此请求多个部分前，请先汇总大纲中的大小

---

inaturalist://taxa/{taxon_id} _资源

• 完整的投影分类单元文档，格式为 application/json；资源读取无法指定部分，因此要获取大纲，请使用 inaturalist_get_taxon
• taxon_id 来自 inaturalist_resolve_name；缓存六小时

---

inaturalist://observations/{observation_id} _资源

• 一条格式为 application/json 的观测记录，包含前 40 条鉴定和前 40 个已填写的观测字段；每项均附有 _total 和 _shown
• observation_id 来自 inaturalist_search_observations；缓存十五分钟

功能

基于 @cyanheads/mcp-ts-core：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可切换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及支持可选 OpenTelemetry 跟踪的结构化日志记录。

iNaturalist 专属功能：

• 无需密钥，即可只读访问 iNaturalist v1 API。上游会忽略自身的 fields= 参数，因此每个响应都会在进程内进行投影（常见的分类单元记录大小为 95 KB）
• 限定区域的工具接受一种区域形式：place_id、lat+lng+radius（单位为公里，最多 500），或由四个角点构成的框。部分填写或混用形式会报错 invalid_geography；d1 晚于 d2 则会报错 inverted_date_range
• 每个端点都有参数允许列表，并会在进程内拒绝上游会悄悄扩大范围或返回零结果的输入：单独的 term_value_id、不可能的日期、未知许可代码
• 流量节奏由服务控制：错开请求启动时间、限制并发数，并设置按 UTC 日计算的预算；超出预算时会报错 rate_budget_exhausted。计数器按进程计算，因此所有调用者共用托管实例的预算。分类单元、地点、受控术语、直方图和相似项集合会缓存；观测查询不会
• 按原样转发许可信息：license_code 为 null 表示保留所有权利；照片的 attribution 必须与图片一同传递；照片仅提供链接，绝不代理。obscured 坐标表示一个地点区域；观察者仅通过 login 标识

便于 Agent 使用的输出：

• 回显已应用的默认值：搜索、物种计数、直方图和排行榜会返回 applied_filters（默认仅包含研究级和野生记录，以及游标强制应用的任何排序）。captive: true 仅选择圈养或栽培记录；false 仅选择野生记录
• 无结果提示会指出最可能导致无结果的筛选条件，以及可用于解码该条件的工具（词汇表使用 inaturalist_list_reference，因为无法识别的值会返回空结果）；超出末页时会指出最后一个有结果的页面
• 所有路径都会披露截断情况：truncated、shown 和 cap；降序排名还会返回 truncationCeiling
• 空筛选数组会被忽略并附带提示；非空注释值仍要求属性数组非空。include: [] 会保留其显式扩展选择
• 未知的 place_id 会返回带类型的 unknown_place_id 指引，提示使用 inaturalist_find_places 解析
• 上游自由文本会按原样渲染为带引号的内容，保留行分隔符、HTML、实体，以及经 CommonMark 解析后的完整字符串。包含 NUL 的字符串会使用带标签的 JSON 字符串字面量；URL 字段会渲染为链接。存在的空扩展、零计数，以及 null 或空描述都会保留显示

开始使用

公共托管实例

公共实例位于 https://inaturalist.caseyjhand.com/mcp，无需安装。通过 Streamable HTTP 将任意 MCP 客户端指向该实例：

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

自托管 / 本地运行

将以下内容添加到 MCP 客户端配置文件中。

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

或使用 npx（无需 Bun）：

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

或使用 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"]
    }
  }
}

使用 Streamable HTTP 时，设置传输方式并启动服务：

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

前提条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 无需 API 密钥：iNaturalist v1 API 无需密钥。已发布的条款要求客户端标识自身，因此默认会发送包含联系 URL 的 User-Agent；覆盖 INATURALIST_USER_AGENT 时也请保留联系 URL。

安装

1. 克隆代码仓库：

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

2. 进入目录：

cd inaturalist-mcp-server

3. 安装依赖：

bun install

4. 配置环境（可选）：

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

配置

变量	描述	默认值
INATURALIST_USER_AGENT	每次向 api.inaturalist.org 发送请求时使用的 User-Agent。任何覆盖值中都应包含联系 URL。	inaturalist-mcp-server/<version> (+<repo url>)
INATURALIST_MIN_REQUEST_INTERVAL_MS	向外发送请求的启动间隔下限，单位为毫秒。默认值可将速率维持在每分钟约 54 次。	1100
INATURALIST_MAX_CONCURRENT_REQUESTS	同时进行的向外请求数上限。	4
INATURALIST_DAILY_REQUEST_BUDGET	每个 UTC 日允许的向外请求数，在进程内计数，并在重启时重置。	9000
INATURALIST_CLAMP_LIMITS	严格布尔值。将超出范围的列表限制截断为 30/30/25/50/50/250，分别用于名称解析、附近地点、搜索、物种计数、相似物种和排行榜，并显示提示、记录日志和计数器。设为 false 可恢复之前公开的架构上限，并拒绝超出范围的输入。	true
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_SESSION_MODE	HTTP 会话模式：stateless、stateful 或 auto。	stateless
MCP_AUTH_MODE	身份验证方式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（debug、info、notice、warning、error）。	info
LOGS_DIR	日志文件目录（仅限 Node.js）。	<project-root>/logs
STORAGE_PROVIDER_TYPE	响应缓存的存储后端：in-memory、filesystem、supabase、cloudflare-kv/r2/d1。	in-memory
OTEL_ENABLED	启用 OpenTelemetry。	false

可查看 .env.example 了解可选覆盖项的完整列表。

运行服务

本地开发

• 构建并运行生产版本：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  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

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/inaturalist-mcp-server。默认会安装 OpenTelemetry 对等依赖；如需省略这些依赖，请使用 --build-arg OTEL_ENABLED=false 构建。

项目结构

目录	用途
src/index.ts	createApp() 入口：身份信息、服务端说明、工具和资源注册、服务初始化。
src/config	使用 Zod 解析和验证服务专用环境变量。
src/mcp-server/tools	工具定义（*.tool.ts），以及共享的筛选器、观测记录和分类单元文档辅助程序。
src/mcp-server/resources	资源定义（*.resource.ts）：分类单元和观测。
src/services/inaturalist	iNaturalist 服务层：允许列表客户端、请求节流器、每日预算、缓存和响应投影。
tests/	单元、集成和冒烟测试，结构与 src/ 对应。

开发指南

开发指南和架构规则请参阅 CLAUDE.md。简而言之：

• 处理器抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录日志，使用 ctx.state 存储数据
• 在 src/index.ts 的 createApp() 数组中注册新工具和资源
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；绝不伪造缺失字段

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

本项目采用 Apache 2.0 许可证。详情请参阅 LICENSE 文件。