gbif-mcp-server

---

概要

Global Biodiversity Information Facility（GBIF）の種の分類、出現記録、データセット、発行者を扱います。名前をバックボーン分類体系に照合し、Darwin Core フィルターを使って 39 億件を超える出現記録を検索・集計し、記録を元のデータセットや発行者までたどることができます。

ツール

ツール	説明
gbif_match_species	学名を GBIF バックボーンと照合し、分類群キー、信頼度、分類を返します
gbif_bulk_match_species	1 回の呼び出しで最大 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 の完全な出現記録を 1 件取得します
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 _tool

• 学名の name を 1 件指定します（一般名の場合は 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 _tool

• strict を指定し、学名の names を渡します。先頭の 50 件が入力順に処理されます。読み取り数の上限調整が有効な場合（デフォルト）、超過した名前は順序と重複を保ったまま unprocessedNames に返され、次回の呼び出しで処理できます
• 各結果には name と matchType が含まれ、一致した場合は taxonKey、matchedTaxonKey（同義語の場合）、confidence も含まれます。一致しない名前は NONE、検索に失敗した名前は error と、分類されている場合は reason を伴う ERROR となります。どちらの場合もバッチ全体は失敗しません

---

gbif_get_species _tool

• バックボーンの taxonKey を 1 件指定します。バックボーンに存在しないキーは not_found、GBIF が解析できないキー（小数、または 32 ビット範囲を超える値）は invalid_filter として失敗します
• 階級ごとのキーを含む分類、authorship、vernacularName、numDescendants、numOccurrences、publishedIn、parentKey を返します。taxonomicStatus が SYNONYM の場合は、acceptedKey と accepted も返します

---

gbif_search_species _ツール

• q 名前の一部（学名または一般名）、rank、isExtinct、およびチェックリストの datasetKey（バックボーンを使う場合は省略）。offset を指定して、1ページあたり最大1,000件を取得します
• 分類群には、チェックリスト上の使用法を示す 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 の大文字・小文字の表記と完全に一致する必要があります。最も範囲の狭い名前がスコープになり、それより広い名前を併せて指定すると分類群を明確にできます。不明な名前は unresolved_taxon_scope、指定された科に属さない属は conflicting_taxon_scope で失敗します。バックボーン以外の datasetKey とスコープを併用すると、一致するものはありません。空のフィルターまたは不正な形式の datasetKey は invalid_filter で失敗します

---

gbif_get_species_classification _ツール

• taxonKey を1つ指定します。classification は界から直近の親までの階層をルートから順に返し、各項目には key、rank、name、scientificName が含まれます
• クエリ対象の分類群は含まれません（gbif_get_species を使用してください）。ルート分類群の場合は、通知とともに空の階層が返されます。不明なキーは not_found、GBIF が解析できないキーは invalid_filter で失敗します

---

gbif_get_species_children _ツール

• taxonKey を1つ指定します。フィルターはありません。offset を指定して、1ページあたり最大1,000件の子分類群を取得できます。不明なキーは not_found、GBIF が解析できないキーは invalid_filter で失敗します
• 各子分類群には key、canonicalName、rank、taxonomicStatus、vernacularName、numOccurrences、numDescendants が含まれます。GBIF は合計件数を返さないため、続きがある場合の truncated とともに、endOfRecords が続きがあるかどうかを示します
• 後続ページが空の場合は、オフセットのリセット方法が案内されます。既存の分類群について最初のページが空の場合に限り、直接の子分類群がないことを意味します

---

gbif_search_occurrences _ツール

• フィルター：taxonKey（推奨。scientificName はシノニムに一致しません）、country、publishingCountry、stateProvince、decimalLatitude／decimalLongitude の範囲または WKT geometry、year、month、basisOfRecord、hasCoordinate、isInCluster、coordinateUncertaintyInMeters、datasetKey、occurrenceStatus、iucnRedListCategory。1ページあたり最大300件を取得します
• 指定された空間フィルターはすべて交差します。geometry と緯度または経度の範囲を組み合わせると、重複する範囲に結果が絞り込まれます
• レコードには key、taxonKey、taxonomicStatus、座標、eventDate と eventTime、basisOfRecord、occurrenceStatus、iucnRedListCategory、datasetKey、issues が含まれます。拡張情報には totalCount、endOfRecords、適用された occurrenceStatus が含まれます
• 検索、件数取得、ファセット取得では、同じ scope が返されます。これは、指定された有効な生物学的フィルターを示し、常に occurrenceStatus を含み、ページネーション制御は除外されます。ANY は返されますが、上流には渡されません。taxonKey と scientificName は OR 条件で組み合わされます。FOSSIL_SPECIMEN、OBSERVATION、UNKNOWN を含む、GBIF の11種類すべての基盤レコード値を指定できます
• 緯度、経度、座標の不確実性はそれぞれ独立した任意の値です。テキストには、ゼロを含め、指定された各値が小数度またはメートルで表示されます
• offset + limit の上限は100,001で、GBIFにはカーソルがありません。これより深いリクエストは pagination_cap_exceeded で失敗します。より多くの一致結果を取得するには、gbif_occurrence_facets の DATASET_KEY ファセットで分割します。拒否されたフィルター値は invalid_filter で失敗します

---

gbif_count_occurrences _tool

• gbif_search_occurrences に記載されているすべての生物学的フィルターを、同じ制約と空間的な交差条件で受け付けます。isGeoreferenced は引き続き hasCoordinate の別名です。どちらか一方、または両方に同じ値を指定できますが、値が矛盾する場合は invalid_filter エラーになります
• occurrenceStatus を適用した count を返します。件数が 100,001 を超える場合は、パーティション分割の経路を示す通知が付与されます。拒否されたフィルター値は invalid_filter エラーになります

---

gbif_get_occurrence _tool

• 検索結果の occurrenceKey を 1 つ指定します。不明なキーは not_found エラーになり、GBIF が解析できない値は invalid_filter エラーになります
• 完全なダーウィンコアレコードを返します。occurrenceStatus（ABSENT は何も見つからなかった調査を意味し、目撃情報ではありません）、座標、gadm 内の GADM レベル 0〜3、eventTime を含む日付、taxonomicStatus、iucnRedListCategory、機関、コレクション、カタログコード、recordedBy、identifiedBy、media、identifiers、issues

---

gbif_occurrence_facets _tool

• 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 のいずれかを指定します。1 ページあたり最大 100 件の値を取得でき（facetLimit、デフォルトは 10）、facetOffset でページを指定します
• gbif_search_occurrences に記載されているすべての生物学的フィルターを、同じ制約と空間的な交差条件で受け付けます。対象データを維持するには、ファセットの呼び出しと各パーティション検索の両方で同じフィルターを繰り返し指定してください。件数順の counts と totalOccurrences を返します。拒否されたスコープ値は invalid_filter エラーになります
• 続きがあることを確認するため、各ファセットリクエストではバケットを 1 つ余分に取得します。余分なバケットがある場合に限り、truncated、shown、cap が表示されます。facetOffset は、公開されたページサイズ分だけ進めてください。最終ページがちょうど満杯の場合、切り捨てフラグは付きません。後続ページが空の場合はオフセットのリセット方法が案内され、最初のページが空の場合は、一致する出現記録が 0 件なのか、そのディメンションにデータがないのかが区別されます
• DATASET_KEY バケットの合計はスコープ全体の合計と一致するため、ページ分割して取得できないほど大きな検索をパーティション分割する場合のファセットとして使用できます。YEAR、MONTH、STATE_PROVINCE、SPECIES_KEY では、該当フィールドを持たないレコードが除外されます。存在と不在を分けるには、occurrenceStatus: ANY とともに facet: OCCURRENCE_STATUS を渡してください

---

gbif_search_datasets _tool

• フィルター：q、type（OCCURRENCE、CHECKLIST、METADATA、SAMPLING_EVENT）、publishingCountry、publishingOrg、hostingOrg。1 ページあたり最大 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 _tool

• datasetKey に UUID を 1 つ指定し、contactLimit を指定します（デフォルトは 10、最大 100。0 を指定すると連絡先の詳細は省略されますが、contactsTotal は保持されます）。不正な形式のキーは invalid_filter エラーになり、不明なキーは not_found エラーになります
• description、citationText、license、doi、recordCount、numConstituents、contactsTotal と contactsReturned を含む contacts、temporalCoverages、geographicCoverages を返します

---

gbif_search_publishers _tool

• q に名前の一部を指定し、country に国コード（alpha-2 または alpha-3、大文字小文字は問いません）を指定します。1 ページあたり最大 1,000 件です
• 組織の key、title、country、city を返します。このキーは gbif_search_datasets の publishingOrg に引き継いで使用できます
• q が空、country が空、または GBIF が解析できない国コードを指定した場合は invalid_filter エラーになります

---

gbif://species/{taxonKey} _リソース

• application/json 形式の分類群レコード：分類名、authorship、vernacularName、acceptedKey と accepted を含む taxonomicStatus、numDescendants
• taxonKey は、符号付き 32 ビットの範囲内にある符号付き 10 進整数です。セグメントは URI デコードを 1 回行い、前後の空白を取り除きます。先頭の +、ゼロ埋め、およびそれらをパーセントエンコードした形式は受け付けます。未知のキーは not_found として失敗します。不正なエスケープ、接尾辞、分数、指数表記、16 進数形式、内部の空白、範囲外の値は、リクエストを送信する前に invalid_filter として失敗します。gbif_match_species のバックボーンキー、または検索結果の nubKey を使用し、その対応付けがない場合は名前を解決してください

---

gbif://dataset/{datasetKey} _リソース

• 連絡先を 10 件に固定した、application/json 形式の gbif_get_dataset レコード
• datasetKey は gbif_search_datasets または出現記録から取得します。未知のキーは 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 の種、出現、データセット、組織の各エンドポイントに、キーなしでアクセスします。すべてのリクエストに識別用の User-Agent を設定します
• 同義語に対応したキー：gbif_match_species は同義語を有効な分類群に解決し、出現ツールはその taxonKey でフィルタリングします
• デフォルトで観測記録を対象：検索、件数、ファセットの各ツールでは、デフォルトで occurrenceStatus を PRESENT に設定し、不在記録を除外します。データセットの recordCount はすべてのステータスを対象とするため、同じキーに対する gbif_count_occurrences の合計より大きくなります
• 厳格な国コード：出現ツールと gbif_search_datasets では、country（記録の観測国）と publishingCountry（発行者の国）は、大文字の ISO 3166-1 alpha-2 のみを受け付けます。ほかの形式では該当なしとして扱われるためです。stateProvince は大文字と小文字を区別して完全一致するため、STATE_PROVINCE ファセットの値を使用してください
• 空のフィルターを拒否：GBIF は空のパラメーターをフィルターなしとして扱うため、空または空白のみの値をオプションのフィルターとして送信すると、クエリの範囲を広げる代わりに invalid_filter として失敗します。フィルターを適用しない場合は、そのフィールドを省略してください

エージェントに適した出力：

• スコープの通知：補足情報には 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 で埋めずに省略：extinct は、GBIF が明示的にフラグを設定した分類群にのみ表示されます
• データセットのメタデータでは、期間、単一の日付、1975-current のようなそのままの期間表記を保持し、未対応の対象範囲情報を明示します。補足の記録数を取得できない場合は、メタデータを保持したまま recordCountNotice を付与します
• 発行者の説明では段落の区切りを保持し、数値文字参照を 1 回デコードします。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 ファイルを参照してください。