gbif-mcp-server

---

概述

来自全球生物多样性信息机构（GBIF）的物种分类、分布记录、数据集和发布者信息。将名称匹配到骨干分类体系，使用 Darwin Core 筛选条件搜索并汇总超过 39 亿条分布记录，并追溯记录所属的数据集和发布者。

工具

工具	描述
gbif_match_species	将学名与 GBIF 主干分类匹配，返回其分类单元键、置信度和分类信息
gbif_bulk_match_species	一次调用匹配最多 50 个学名，按输入顺序为每个名称返回一个结果
gbif_get_species	按键获取主干分类单元：分类信息、命名者信息、异名情况、俗名和计数
gbif_search_species	按名称片段、分类阶元或界、科、属名称搜索或浏览主干分类
gbif_get_species_classification	返回分类单元的上级分类链，按从界到直接上级的顺序排列
gbif_get_species_children	列出分类单元的直接下级分类单元，例如科中的属或属中的种
gbif_search_occurrences	按分类单元、地点、日期、记录依据、存在/缺失状态和 IUCN 类别搜索 39 亿条以上的出现记录
gbif_count_occurrences	统计符合筛选条件的出现记录数，不获取记录本身
gbif_get_occurrence	按键获取一条完整的 Darwin Core 出现记录
gbif_occurrence_facets	按国家、年份、数据集、分类单元、状态及其他维度汇总出现记录数
gbif_search_datasets	按关键词、类型、发布国家或发布/托管组织搜索数据集
gbif_get_dataset	按 UUID 获取完整数据集元数据：引用信息、联系人、许可证、DOI、覆盖范围
gbif_search_publishers	按名称或国家搜索 GBIF 注册的发布组织

资源

资源	描述
gbif://species/{taxonKey}	GBIF 主干分类中的分类单元记录：分类信息、命名者信息、异名状态、俗名
gbif://dataset/{datasetKey}	数据集元数据：标题、描述、引用信息、许可证、联系人、覆盖范围

这两种资源也可以通过 gbif_get_species 和 gbif_get_dataset 访问；许多 MCP 客户端仅支持工具，不会显示资源。

能力参考

gbif_match_species _工具

• 一个学名 name（常用名请使用 gbif_search_species），可选参数包括 strict、用于消除歧义的 kingdom 和预期的 rank
• 返回 taxonKey（传递给出现记录工具的已接受分类单元）；如果解析出异名，还会返回 matchedTaxonKey；此外还返回 matchType（EXACT、FUZZY、HIGHERRANK）、confidence（0–100；低于 80 时应复核）以及各分类阶元均带键值的分类信息
• matchType 为 NONE 时以 no_match 失败；kingdom 为空时以 invalid_filter 失败

---

gbif_bulk_match_species _工具

• 学名 names，以及 strict；按输入顺序处理前 50 个名称。启用读取限制（默认）时，多出的名称会按原顺序（包括重复项）返回到 unprocessedNames，供下次调用使用
• 每个结果都包含 name 和 matchType；匹配成功时还包含 taxonKey、matchedTaxonKey（异名）和 confidence；未匹配的名称为 NONE，查询失败则为 ERROR，并包含 error 和（如果已分类）reason，这两种情况都不会导致整个批次失败

---

gbif_get_species _工具

• 一个主干分类 taxonKey；主干中不存在的键以 not_found 失败；GBIF 无法解析的键（小数或超出 32 位范围）以 invalid_filter 失败
• 返回包含各分类阶元键的分类信息、authorship、vernacularName、numDescendants、numOccurrences、publishedIn 和 parentKey；当 taxonomicStatus 为 SYNONYM 时，还会返回 acceptedKey 和 accepted

---

gbif_search_species _工具

• q 名称片段（科学名称和俗名）、rank、isExtinct 和清单 datasetKey（使用主干分类时省略）；每页最多 1,000 条，可通过 offset 分页
• 分类单元包含清单用法 key、可选的来源 datasetKey 和映射后的主干分类 nubKey、rank、taxonomicStatus、分类名称、numOccurrences 和 numDescendants；补充信息会报告 totalCount、endOfRecords 和应用的 taxonScope。有 nubKey 时，分布记录查询会使用它；否则会通过 gbif_match_species 解析名称。省略 datasetKey 时，使用 GBIF Backbone Taxonomy d7dddbf4-2cf0-4f39-9b2a-bb099caae36c
• kingdom、family 和 genus 接受名称，并按 GBIF 的大小写精确匹配；范围最窄的字段生效，同时提供 kingdom 和更窄范围的字段时，kingdom 用于消除歧义。未知名称会导致 unresolved_taxon_scope 错误；不属于指定科的属会导致 conflicting_taxon_scope 错误；范围与非主干分类 datasetKey 搭配时则不会匹配到任何结果。筛选条件为空或 datasetKey 格式错误时，会导致 invalid_filter 错误

---

gbif_get_species_classification _工具

• 提供一个 taxonKey；返回从界到直接上级、以根为先的 classification，其中每项包含 key、rank、name 和 scientificName
• 不包含所查询的分类单元（请使用 gbif_get_species）；根分类单元会返回空分类链及提示，未知键会导致 not_found 错误，无法解析的 GBIF 键会导致 invalid_filter 错误

---

gbif_get_species_children _工具

• 提供一个 taxonKey，每页最多返回 1,000 个子级，可通过 offset 分页；不支持筛选。未知键会导致 not_found 错误，无法解析的 GBIF 键会导致 invalid_filter 错误
• 每个子级包含 key、canonicalName、rank、taxonomicStatus、vernacularName、numOccurrences 和 numDescendants；GBIF 不会报告总数，因此 endOfRecords（还有更多结果时会带有 truncated）是继续获取结果的信号
• 后续页面为空时会提供重置偏移量的指引；对于已存在的分类单元，只有第一页为空才表示没有直接子级

---

gbif_search_occurrences _工具

• 筛选条件：taxonKey（优先使用；scientificName 不匹配异名）、country、publishingCountry、stateProvince、decimalLatitude/decimalLongitude 范围框或 WKT geometry、year、month、basisOfRecord、hasCoordinate、isInCluster、coordinateUncertaintyInMeters、datasetKey、occurrenceStatus、iucnRedListCategory；每页最多 300 条
• 提供的所有空间筛选条件会取交集：将 geometry 与纬度或经度范围组合时，结果会限定在它们的重叠范围内
• 记录包含 key、taxonKey、taxonomicStatus、坐标、eventDate 和 eventTime、basisOfRecord、occurrenceStatus、iucnRedListCategory、datasetKey 和 issues；补充信息会报告 totalCount、endOfRecords 和应用的 occurrenceStatus
• 搜索、计数和分面结果会回显相同的 scope：实际生效的已提供生物学筛选条件，其中始终包含 occurrenceStatus，但不包含分页控制参数。回显 ANY，但不会向上游传递。taxonKey 和 scientificName 以 OR 组合。支持全部 11 种 GBIF 的记录依据值，包括 FOSSIL_SPECIMEN、OBSERVATION 和 UNKNOWN
• 纬度、经度和坐标不确定度是彼此独立的可选信息；文本会以十进制度或米为单位，显示每个已提供的值，包括零
• offset + limit 上限为 100,001，且 GBIF 不提供游标；请求更深的结果会导致 pagination_cap_exceeded 错误。如需获取更多匹配结果，可按 gbif_occurrence_facets 中的 DATASET_KEY 分面进行分区。筛选值被拒绝时，会导致 invalid_filter 错误

---

gbif_count_occurrences _工具

• 接受 gbif_search_occurrences 中列出的所有生物筛选条件，并遵循相同的约束和空间相交规则。isGeoreferenced 仍是 hasCoordinate 的别名；单独传入任一参数或同时传入且值相同均有效，值冲突则会以 invalid_filter 失败
• 返回 count，并在丰富数据时应用 occurrenceStatus；计数超过 100,001 时会附带一条注明分区路径的提示，筛选值不被接受时会以 invalid_filter 失败

---

gbif_get_occurrence _工具

• 传入搜索结果中的一个 occurrenceKey；未知的键会以 not_found 失败，GBIF 无法解析的键会以 invalid_filter 失败
• 完整的 Darwin Core 记录：occurrenceStatus（ABSENT 表示调查未发现任何个体，并非目击记录）、坐标、gadm 下的 GADM 0–3 级、包含 eventTime 的日期、taxonomicStatus、iucnRedListCategory、机构、馆藏和目录代码、recordedBy 和 identifiedBy、media、identifiers 以及 issues

---

gbif_occurrence_facets _工具

• facet 可以是 COUNTRY、STATE_PROVINCE、YEAR、MONTH、BASIS_OF_RECORD、DATASET_KEY、PUBLISHING_COUNTRY、KINGDOM_KEY、PHYLUM_KEY、CLASS_KEY、ORDER_KEY、FAMILY_KEY、GENUS_KEY、SPECIES_KEY、OCCURRENCE_STATUS、IUCN_RED_LIST_CATEGORY 之一；每页最多 100 个值（facetLimit，默认值为 10），使用 facetOffset 分页
• 接受 gbif_search_occurrences 中列出的所有生物筛选条件，并遵循相同的约束和空间相交规则。请在 facet 调用和每次分区搜索中重复这些条件，以保持总体范围不变。返回按计数排序的 totalOccurrences 和 counts；范围值不被接受时会以 invalid_filter 失败
• 每个 facet 请求都会多获取一个分桶，以确认是否还有后续结果。只有在存在该分桶时才会显示 truncated、shown 和 cap；请按公开的页面大小递增 facetOffset。最后一页若恰好填满，则不会带有截断标记。后续页面为空时会提供重置偏移量的指引；第一页为空时，则会区分没有匹配的 occurrence 与该维度没有数据
• DATASET_KEY 分桶合计等于范围的完整总数，因此当搜索结果过大而无法分页时，可用此 facet 进行分区；YEAR、MONTH、STATE_PROVINCE 和 SPECIES_KEY 会排除缺少该字段的记录。若要按存在/缺失情况拆分，请传入 facet: OCCURRENCE_STATUS 和 occurrenceStatus: ANY

---

gbif_search_datasets _工具

• 筛选条件：q、type（OCCURRENCE、CHECKLIST、METADATA、SAMPLING_EVENT）、publishingCountry、publishingOrg、hostingOrg；每页最多 1,000 个
• 返回 key、title、type、license、doi、recordCount，以及 300 个字符的 description 预览；descriptionTruncated 标记预览是否经过截断（gbif_get_dataset 可获取完整文本）
• publishingOrg 匹配拥有相关数据的组织，也是 gbif_search_publishers 的常用关联方式；hostingOrg 匹配托管该数据集的组织，两者同时使用时取交集。二者均须使用小写 UUID 格式；其他格式，以及任何不被接受的筛选值，都会以 invalid_filter 失败

---

gbif_get_dataset _工具

• 传入一个 datasetKey UUID 和 contactLimit（默认值为 10，最大值为 100；设为 0 会省略联系人详情，但保留 contactsTotal）；键格式错误时会以 invalid_filter 失败，键未知时则会以 not_found 失败
• 返回 description、citationText、license、doi、recordCount、numConstituents、包含 contactsTotal 和 contactsReturned 的 contacts、temporalCoverages 以及 geographicCoverages

---

gbif_search_publishers _工具

• q 名称片段和 country（alpha-2 或 alpha-3 格式，不区分大小写）；每页最多 1,000 个
• 返回组织的 key、title、country 和 city；该键可作为 publishingOrg 用于 gbif_search_datasets
• q 为空、country 为空，或 GBIF 无法解析该国家时，会以 invalid_filter 失败

---

gbif://species/{taxonKey} _资源

• 作为 application/json 的分类单元记录：分类名称、authorship、vernacularName、包含 acceptedKey 和 accepted 的 taxonomicStatus、numDescendants
• taxonKey 是有符号 32 位整数范围内的有符号十进制整数。该路径段会进行一次 URI 解码，并去除前后空格；接受前导 +、前导零及其百分号编码形式。未知键会报错 not_found；格式错误的转义序列、后缀、小数、指数形式、十六进制形式、嵌入的空格以及超出范围的值会在发起请求前报错 invalid_filter。请使用 gbif_match_species 返回的骨干分类键，或搜索结果中的 nubKey；如果没有该映射，请解析其名称

---

gbif://dataset/{datasetKey} _资源

• gbif_get_dataset 记录，以 application/json 返回，联系人数量固定为 10
• datasetKey 来自 gbif_search_datasets 或 occurrence 记录；未知键会报错 not_found，格式错误的键会报错 invalid_filter

功能

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

GBIF 特有功能：

• GBIF API v1 的物种、occurrence、数据集和组织端点，无需密钥，并在每个请求中使用标识性 User-Agent
• 同义词安全键：gbif_match_species 会将同义词解析为已接受的分类单元，occurrence 工具会使用该 taxonKey 进行筛选
• 默认仅查找有记录的观测：搜索、计数和 facet 工具默认将 occurrenceStatus 设为 PRESENT，排除缺失记录。数据集 recordCount 涵盖所有状态，因此其数值会高于同一键对应的 gbif_count_occurrences 总数
• 严格的国家代码：在 occurrence 工具和 gbif_search_datasets 中，country（记录的观测地）和 publishingCountry（发布者所在国家）仅接受大写 ISO 3166-1 alpha-2 代码，因为其他形式在此处会静默匹配不到结果。stateProvince 按原样区分大小写匹配，因此请从 STATE_PROVINCE facet 中获取值
• 拒绝空白筛选条件：GBIF 会将空参数视为无筛选条件，因此可选筛选字段若为空或仅包含空格，会报错 invalid_filter，而不是扩大查询范围。若不使用某个字段，请将其省略

适用于 Agent 的输出：

• 范围回显：丰富化结果会报告 totalCount、endOfRecords、应用的 occurrenceStatus 和解析出的 taxonScope，并在结果为空、总数超过上限以及 stateProvince 未匹配到任何内容时提供提示
• 优雅处理部分失败：gbif_bulk_match_species 会为每个名称返回一条 NONE 或 ERROR 记录，而不是使整个批次失败
• 类型化错误：invalid_filter、not_found、no_match、unresolved_taxon_scope、conflicting_taxon_scope 和 pagination_cap_exceeded，每种错误都附有恢复提示
• 省略稀疏字段，而非填充为 null：仅当 GBIF 明确标记某分类单元时，才会出现 extinct
• 数据集元数据会保留时间范围、单个日期以及 1975-current 等原始时段；不支持的覆盖范围条目会予以说明。若无法获取补充记录数，会保留元数据并附带 recordCountNotice
• 发布者描述会保留段落换行，并对数字字符引用解码一次；Markdown 输出会按字面呈现发布者文本

入门

公共托管实例

可通过 https://gbif-biodiversity.caseyjhand.com/mcp 使用公共实例，无需安装。通过 Streamable HTTP 将任意 MCP 客户端指向该实例：

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

自托管 / 本地

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

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

或者使用 npx（无需 Bun）：

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

或者使用 Docker：

{
  "mcpServers": {
    "gbif-biodiversity-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/gbif-biodiversity-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+）。
• 无需凭据：此服务调用的 GBIF 端点是公开的。

安装

1. 克隆仓库：

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

2. 进入目录：

cd gbif-biodiversity-mcp-server

3. 安装依赖：

bun install

4. 配置环境：

cp .env.example .env
# optionally set GBIF_USER_AGENT to a contact URL or email

配置

变量	描述	默认值
GBIF_BASE_URL	GBIF API 基础 URL。	https://api.gbif.org/v1
GBIF_CLAMP_READ_LIMITS	将超出限制的读取数量限制在文档规定的上限内，并披露请求值和应用值。批量匹配会处理前 50 个名称，并在 unprocessedNames 中返回其余名称。设为 false 可改为公布并强制执行拒绝上限。严格的布尔值解析会拒绝格式错误的值。	true
GBIF_REQUEST_TIMEOUT_MS	每个请求的 HTTP 超时时间，单位为毫秒。	10000
GBIF_USER_AGENT	每次 GBIF 请求中发送的 User-Agent。GBIF 要求集成方使用联系 URL 或电子邮件地址标识自身。	服务名称、版本和仓库 URL
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_SESSION_MODE	HTTP 会话模式：stateless、stateful 或 auto。src/index.ts 声明为 stateless；设置此项可覆盖该值。	stateless
MCP_AUTH_MODE	身份验证：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（debug、info、warning、error 等）。	info
LOG_TOOL_FAILURE_PAYLOADS	记录每次失败的工具调用参数和结果，按键名进行脱敏，并限制在 LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（默认 16384）以内。自由格式值中的机密不会被脱敏。	false
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:http
  # or
  bun run start:stdio
  

• 运行检查和测试：

  bun run devcheck  # Lints, formats, type-checks, and more
  bun run test      # Runs the test suite
  

Docker

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

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

项目结构

目录	用途
src/mcp-server/tools	工具定义（*.tool.ts）和共享工具实用程序。共 13 个工具，涵盖物种分类、出现记录、数据集和发布者。
src/mcp-server/resources	资源定义。包含物种和数据集资源。
src/services/gbif	GBIF API 服务层：提供重试、超时和错误映射的 HTTP 客户端，以及原始响应类型。
src/config	使用 Zod 解析和验证服务专用环境变量。
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 文件。