# jaxa-earth-mcp

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

個人開発者が作成した再利用可能な MCP(Model Context Protocol)ツールです。
JAXA が公開している衛星観測データ配信サービス [JAXA Earth API](https://data.earth.jaxa.jp/)
の 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](https://sharaku.eorc.jaxa.jp/GSMaP/faq/GSMaP_faq04.html)）。時系列取得時に `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。

```bash
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 .
```

インストール確認:

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

---

## MCP サーバーの登録

### Claude Code（CLI）

```bash
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`）に以下を追加します。
パスは環境に合わせて絶対パスで記述してください。

```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](https://data.earth.jaxa.jp/) /
[利用規約](https://earth.jaxa.jp/policy/en.html)

---

## 免責

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