jaxa-earth-mcp

JAXA Earth API を Claude Code / Claude Desktop から対話的に扱うための軽量 MCP ラッパー。

個人開発者が作成した再利用可能な MCP(Model Context Protocol)ツールです。 JAXA が公開している衛星観測データ配信サービス JAXA Earth API の Python パッケージ（jaxa-earth）を薄くラップし、地点の時系列取得・データセット情報照会・ 領域画像生成を AI エージェントから呼び出せるようにします。

• 追加の API キー・ユーザー登録・課金は不要（JAXA Earth API は登録不要・無償）
• 依存は最小限（jaxa-earth / mcp / numpy / requests）
• サーバーは標準入出力（stdio）で動作

本リポジトリは JAXA 公式のものではありません。データの権利は JAXA に帰属します （利用上の注意 参照）。

---

提供ツール

ツール	概要
list_datasets(keyword?)	データセットを検索。keyword 省略時は主要データセットを返す。指定時は STAC カタログ全体を ID 部分一致で検索。
get_dataset_info(dataset_id)	分解能・提供期間・単位・出典（citation/DOI）・ライセンス・クレジット表記例・利用上の注意を返す。
get_point_timeseries(dataset_id, lat?, lon?, start_date?, end_date?)	地点の時系列（日付・値の配列＋統計）。lat/lon 省略時は新潟県魚沼地域（37.2250, 138.9689）。
get_area_image(dataset_id, bbox, date)	指定領域・日付の PNG を outputs/ に保存し、パス等を返す。

実装上の主な挙動（実測で確認済み）

• bbox 自動拡張: get_point_timeseries は点まわりの矩形を データセットの分解能 （STAC の je:ppu_max）から動的に算出します。粗い ~5km 級（GSMaP/SMC など）は ±0.3° 程度に広げて地域平均を取り、高分解能（DSM 30m）は点に近い矩形を使います。 固定値ではありません。
• 長期間の自動分割: JAXA Earth API は 1 リクエスト最大 100 日の制約があります。 期間がこれを超える場合、内部で 90 日ごとに分割取得し、結合して 1 本の時系列で返します。
• 静的データの単発取得: 標高（ALOS DSM）のような時間変化しないデータは、 start_date/end_date を無視して単発取得します。
• 欠測は補間しない: 雲などで観測が欠けた場合、その値は null（NaN）のまま返します （前後の値でつなぎません）。
• 取得失敗はそのまま返す: 想定外のエラーは握りつぶさず、内容を返します。

---

対応データセット（主要 5 種）

略称	内容	単位	分解能(概算)	備考
GSMaP	降水（日次）	mm/hr	約11km (0.1°)	値は日平均降水強度。日積算量[mm]=値×24（JAXA GSMaP FAQ Q4）。時系列取得時に derived.total_mm_estimated として自動換算。
GCOM-C LST	地表面温度（日中・日次）	Kelvin	約2.8km (1/40°)	地表面温度であり気温ではない。雲欠測あり。
GCOM-C NDVI	植生指数（日中・半月）	無次元	約2.8km (1/40°)	分解能が粗く圃場単位でなく地域傾向。雲欠測あり。
ALOS AW3D30	数値表層モデル（標高）	m	約30m	静的データ（2024年4月版 / v4.1）。
GCOM-W SMC	土壌水分量（日中・日次）	%（体積含水率）	約11km (0.1°)	マイクロ波観測で雲を透過。

単位は jaxa-earth が COG メタデータから読む値（cinfo.unit）を実測で確認しています。 keyword 検索で上記以外のデータセット（GCOM-C は 39 種など、全体で 100 以上）も利用できます。

分解能の注記: GCOM-C LST/NDVI の API 配信グリッドは COG の GeoTIFF タグ （ModelPixelScale=0.025°、90°タイル=3600px）を実測して 1/40°（約2.8km） と確認しました。 一部のデータセットで STAC の citation に「1/24 deg」等の実グリッドと異なる表記や、 description の取り違え（NDVI に「Land surface temperature」と記載）が見られます。 本ツールは分解能を ppu_max／COG 実測値から算出しており、get_dataset_info の resolution.note にこの不一致を明記します。

---

セットアップ

前提: Python 3.10 以上、macOS / Linux / Windows。

git clone <this-repo> jaxa-earth-mcp
cd jaxa-earth-mcp

python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -e .

インストール確認:

python -c "import jaxa_earth_mcp, mcp, jaxa.earth; print('OK')"

---

MCP サーバーの登録

Claude Code（CLI）

claude mcp add jaxa-earth \
  --env JAXA_MCP_OUTPUTS="$(pwd)/outputs" \
  -- "$(pwd)/.venv/bin/jaxa-earth-mcp"

# 確認（Status: ✔ Connected になれば成功）
claude mcp get jaxa-earth

登録後、Claude Code のプロンプトから自然文で呼び出せます。例:

• 「2026年4月から今日までの魚沼の日次降水量の推移と合計を出して」
• 「魚沼の8月のNDVIとその分解能・注意事項を教えて」

Claude Desktop

設定ファイル（macOS: ~/Library/Application Support/Claude/claude_desktop_config.json、 Windows: %APPDATA%\Claude\claude_desktop_config.json）に以下を追加します。 パスは環境に合わせて絶対パスで記述してください。

{
  "mcpServers": {
    "jaxa-earth": {
      "command": "/absolute/path/to/jaxa-earth-mcp/.venv/bin/jaxa-earth-mcp",
      "env": {
        "JAXA_MCP_OUTPUTS": "/absolute/path/to/jaxa-earth-mcp/outputs"
      }
    }
  }
}

Windows の command は ...\\.venv\\Scripts\\jaxa-earth-mcp.exe を指定します。 設定後、Claude Desktop を再起動してください。

python -m jaxa_earth_mcp.server でも起動できます。その場合は command に venv の python を、args に ["-m", "jaxa_earth_mcp.server"] を指定します。

---

使い方（ツール詳細）

get_point_timeseries

dataset_id : データセットID（list_datasets で確認）
lat, lon   : 省略時は魚沼（37.2250, 138.9689）
start_date : "YYYY-MM-DD"（時系列データで必須）
end_date   : "YYYY-MM-DD"（時系列データで必須）

返り値には series（{date, value} の配列、欠測は value: null）、stats （count / missing / mean / min / max）、aggregation（使用した bbox と分解能）、 unit、credit が含まれます。

降水強度[mm/hr]の単純合計は物理的に無意味なため stats に sum は持ちません。 GSMaP（mm/hr）の場合のみ derived に日積算量[mm/day]への換算 （series_mm と total_mm_estimated、換算根拠付き）を返します。

get_area_image

dataset_id : データセットID
bbox       : [min_lon, min_lat, max_lon, max_lat]
date       : "YYYY-MM-DD"（最も近い観測日を自動選択。静的データでは無視）

outputs/ に PNG を保存し、image_path を返します。

---

クレジット・ライセンス

• コード: MIT License。
• データ: JAXA Earth 研究データ利用規約に従います。商用利用は同規約適用データで可能です。 各データセットの詳細ライセンスは STAC の license / providers に定義されています。
• クレジット表記例（get_dataset_info が各データセットの表記例を返します）:
  • データ: Credit: <データセット名> (JAXA)（例: Credit: GSMaP (JAXA)）
  • API 利用: Image: Created using the JAXA Earth API

出典・規約の一次情報: JAXA Earth API / 利用規約

---

免責

本リポジトリは個人開発による非公式ツールです。JAXA が提供・保証するものではありません。 データの内容・可用性については JAXA Earth API の提供状況に依存します。