inaturalist-mcp-server

---

概要

iNaturalist は、植物、動物、菌類について、地理情報が付与された市民科学観察記録を 3 億 8,700 万件以上収録するインデックスです。地域、日付、分類群、注釈で目撃情報を検索し、記録の背景にある識別スレッドを読み、分類群がいつ出現するかをグラフ化し、地域の種を順位付けし、よく似た種が最も頻繁に何と混同されるかを確認できます。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	範囲と期間に記録された異なる種を観察数の多い順に順位付けします。必要に応じて、1 人の観察者または 1 つのプロジェクトに絞り込めます
inaturalist_get_histogram	範囲内の分類群について、記録された月、週、年を示す季節性ヒストグラムを作成します
inaturalist_get_leaderboard	範囲、期間、分類群について、最も活動的な観察者または識別者を順位付けします
inaturalist_get_similar_species	属レベル以下の分類群が誤って識別されることの多い分類群を、修正数の多い順に一覧表示します
inaturalist_get_taxon	分類群のプロファイルを取得します。分類経路、機関別の保全リスト、百科事典の概要、写真、下位分類群が含まれます

リソース

リソース	説明
inaturalist://taxa/{taxon_id}	数値の分類群 ID による分類群プロファイル。注入可能なコンテキストとして提供されます
inaturalist://observations/{observation_id}	識別履歴を展開した 1 件の観察記録。注入可能なコンテキストとして提供されます

どちらのリソースも、inaturalist_get_taxon と inaturalist_get_observation からも取得できるデータを提供します。これは、MCP リソースを表示しないクライアント向けです。

公開されている inaturalist-guide では、識別情報の出所、照合対象のコホート、注釈、呼び出し全体にわたる証拠の網羅性を説明しています。npm、プラグイン、MCPB、Docker の各インストールに同梱されています。MCP スキルの検出に対応したクライアントからは、直接取得できます。SDK は 2 つのドメインリソースと併せて、スキルリソースも公開します。

機能リファレンス

inaturalist_list_reference _ツール

• topic で 1 つのテーブルを選択します。controlled_terms（ライブ取得）、quality_grades、licenses、ranks、iconic_taxa、conservation_status_codes のいずれかです。taxon_id は controlled_terms でのみ有効で、指定すると、その分類群について記録された注釈の組み合わせと件数を示す 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 も含まれます。該当する候補がない場合、エラーではなく found: false と guidance が返されます

---

inaturalist_find_places _ツール

• q（場所名の接頭辞）を指定するか、nelat、nelng、swlat、swlng の 4 つすべてを指定します。どちらでもない場合は invalid_geography になります。per_page は最大 30（デフォルトは 10）で、範囲を指定する場合にのみ各リストに適用されます
• q を指定すると places[] が返され、範囲を指定すると standard[] と community[] が返されます。各場所には id、bbox、ancestor_place_ids、place_type、admin_level、location が含まれ、境界ポリゴンは除外されます

---

inaturalist_search_observations _tool

• 1つのエリア形式に加え、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では、7つのCCコードをOR結合で指定できます。photo_licenseは、記録自体のlicense_codeとは無関係に、指定コードに該当する写真が1枚でもある記録を対象にします。
• シリアライズされた応答全体が50,000 UTF-8バイト以内に収まるよう、レコード単位で先頭から返します。順序付きのdeferredには、返却されなかったレコードの観察IDが含まれます。ページの続きに進む前に、同じincludeを指定してinaturalist_get_observationで取得してください。

---

inaturalist_get_observation _tool

• observation_idを1～100個指定します。重複は最初に現れた順序を保って除去され、最初の異なるID 10個が1回の上流リクエストで試行され、残りはdeferredに返されます。制限値の適用を無効にすると、指定できるIDは最大10個です。includeのデフォルトは["identifications"]で、comments、photos、annotations、soundsも指定できます。
• 解決されたレコードはリクエスト順にobservationsで返され、試行したものの見つからなかったIDはunresolvedに返されます。1件も解決されず、保留中のIDもない場合に限り、not_foundとして失敗します。community_taxon、description、および値が入力されたobservation_fieldsが追加されます。文字列は省略されないため、詳細応答に共通のバイト数上限はありません。
• 識別情報、コメント、観察フィールドは40件の上限を共有します。各レコードでは配列ごとにmax(4, floor(40 / records returned))件を保持し、*_shownの横に*_totalを報告します。

---

inaturalist_get_species_counts _tool

• 1つのエリア形式に加え、分類群、日付、品質グレード、飼育下、注釈、代表的な分類群、観察者、プロジェクトの検索フィルターを指定できます。適用されるper_pageは最大50、デフォルトは25で、pageでオフセットを指定します。
• 行にはposition（1ページ目から数えた絶対位置）、taxon_id、observation_countが含まれます。truncationCeilingは表示された最後の件数で、ページ外にこれを上回る件数はありません。

---

inaturalist_get_histogram _tool

• 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を指定すると推移を絞り込めます。
• すべての区分を順番に、値が0の区分も含めて返し、全区分のtotalも返します。範囲の先頭から最大800区分までに制限され、truncated／shown／capが含まれます。
• d1／d2は観察日を絞り込み、created_d1／created_d2はアップロード日を別途絞り込みます。date_fieldは区分に使用する日付を選択しますが、どちらのフィルターペアにも影響しません。

---

inaturalist_get_leaderboard _tool

• kindにはobserversまたはidentifiersを指定し、1つのエリア形式、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 の順にランク付けされ、上限によって対象セットが切り詰められた場合は truncationCeiling が含まれます

---

inaturalist_get_taxon _ツール

• taxon_id を1つ指定します。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 から取得します。キャッシュ期間は6時間です

---

inaturalist://observations/{observation_id} _リソース

• application/json 形式で1件の観察を返します。最初の40件の同定と、値が入力された最初の40件の観察フィールドが含まれ、それぞれの _total と _shown が併記されます
• observation_id は inaturalist_search_observations から取得します。キャッシュ期間は15分です

機能

@cyanheads/mcp-ts-core を基盤としており、stdio と Streamable HTTP のトランスポート、プラグイン可能な認証（none／jwt／oauth）、切り替え可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションの OpenTelemetry トレーシングに対応した構造化ログを備えています。

iNaturalist 固有の機能：

• iNaturalist v1 API を、キー不要かつ読み取り専用で利用できます。上流 API は独自の fields= パラメーターを無視するため、すべてのレスポンスをプロセス内で必要な形式に絞り込みます（一般的な分類群レコードでも 95 KB で届きます）。
• エリアを指定するツールは、次のいずれかの形式を受け取ります。place_id、キロメートル単位の lat＋lng＋radius（最大 500）、または四隅を指定するボックスです。不完全な形式や混在した形式は invalid_geography としてエラーになり、d1 が d2 より後の場合は inverted_date_range としてエラーになります。
• エンドポイントごとに許可するパラメーターを制限し、上流 API では警告なしに検索範囲が拡大またはゼロ件になる入力もプロセス内で拒否します。対象は、単独の term_value_id、ありえない日付、不明なライセンスコードです。
• トラフィックを適切な間隔で制御します。リクエストの開始間隔を空け、同時実行数に上限を設け、UTC の日単位の予算を設定し、超過時は rate_budget_exhausted としてエラーになります。カウンターはプロセス単位のため、ホストされたインスタンスのすべての呼び出し元で共有されます。分類群、場所、制御語彙、ヒストグラム、類似セットはキャッシュされますが、観察データのクエリはキャッシュされません。
• ライセンス情報はそのまま中継します。license_code が null の場合、すべての権利が留保されています。写真の attribution は画像とともに引き継ぐ必要があり、写真はリンクとして提供し、プロキシ配信はしません。obscured の座標は地域を示し、観察者は login のみで識別されます。

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

• 適用したデフォルトを明示します。検索、種の件数、ヒストグラム、リーダーボードは applied_filters を返します（デフォルトでは研究グレードかつ野生のみで、カーソルによって強制された並べ替えも含まれます）。captive: true は飼育または栽培された記録のみを選択し、false は野生の記録のみを選択します。
• 検索結果が 0 件の場合、原因として最も可能性の高いフィルターと、それを確認できるツールを通知します（語彙については、認識されない値を指定すると結果が返らないため、inaturalist_list_reference を案内します）。結果が存在する最後のページを超えている場合は、そのページ番号を通知します。
• どの経路でも切り詰めたことを明示します。truncated、shown、cap に加え、降順ランキングでは truncationCeiling も返します。
• 空のフィルター配列は通知を添えて無視されます。空でない注釈値には、空でない属性配列も必要です。include: [] は明示的な展開選択として維持されます。
• 不明な place_id を指定すると、inaturalist_find_places で解決するための案内を含む、型付きの unknown_place_id が返されます。
• 上流からの自由入力テキストは、引用符付きのリテラルとして表示され、改行、HTML、エンティティ、CommonMark で解析した後の完全な文字列も保持されます。NUL を含む文字列は、ラベル付きの JSON 文字列リテラルを使用します。URL フィールドはリンクとして表示されます。空の展開結果、0 件のカウント、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 で上書きする場合も、連絡先を含めてください。

インストール

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 の 1 日あたりに許可されるアウトバウンドリクエスト数です。プロセス内でカウントされ、再起動時にリセットされます。	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 サービスレイヤーです。許可リスト方式のクライアント、ペーサー、1 日あたりの予算、キャッシュ、レスポンスのプロジェクションが含まれます。
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 の下でライセンスされています。詳細については、LICENSE ファイルを参照してください。