🪐 ✨ Earthdata MCP Server

🪐 ✨ Earthdata MCP Server

Earthdata MCP Server は、NASA Earth Data とやり取りするためのツールを提供する Model Context Protocol (MCP) サーバーの実装です。

これは reactor_mcp_server の拡張として構築されているため、2 通りの方法で動作します。

• 単体で動作: earthdata-mcp-server start は Earthdata ツールのみを stdio またはストリーミング可能な HTTP 経由で提供します。
• ツールセットとして動作: 任意の reactor_mcp_server ホストと並べてインストールすると、それを要求するクライアントに対してオプトインの earthdata ツールセットとして検出され、提供されます: /mcp?earthdata。Datalayer MCP Server は、ノートブックやサンドボックスと並べてこの方法で提供します。

このサーバーは意図的に Earthdata 専用です。ノートブックやランタイムのツールについては、それらと同じホスト上で並べて提供するか、mcp-compose を使って jupyter-mcp-server と組み合わせてください。

主な機能

• NASA Earthdata でのデータセット検出
• 時間フィルターとバウンディングボックスフィルターを使用したグラニュール検索
• 明示的な実行モードを備えた柔軟なダウンロードワークフロー

はじめに

ローカルインストール

pip install earthdata-mcp-server

# stdio, for a client that launches the server
earthdata-mcp-server start

# streamable HTTP, at http://localhost:4040/mcp
earthdata-mcp-server start --transport streamable-http --port 4040

オプション	環境変数	デフォルト
--transport	TRANSPORT	stdio (または streamable-http)
--host	HOST	0.0.0.0
--port	PORT	4040

reactor MCP ホスト上のツールセットとして

pip install earthdata-mcp-server "reactor_mcp_server[server]"
reactor-mcp-server --port 4040

http://localhost:4040/mcp?earthdata に接続するクライアントは、インストールされている他のものと並べて Earthdata ツールを取得します。/toolsets はホストが提供するものの一覧を表示します。コードでは次のようになります。

from reactor_mcp_server import build_host, create_mcp_app
from earthdata_mcp_server import EarthdataExtension

app = create_mcp_app(build_host([EarthdataExtension()]), path="/mcp")

EarthdataExtension(default=True) は、何も指定しないクライアントに対してツールセットを提供します。

Claude Desktop での Docker

{
  "mcpServers": {
    "earthdata": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "EARTHDATA_USERNAME",
        "-e", "EARTHDATA_PASSWORD",
        "datalayer/earthdata-mcp-server:latest"
      ],
      "env": {
        "EARTHDATA_USERNAME": "your_username",
        "EARTHDATA_PASSWORD": "your_password"
      }
    }
  }
}

Linux ホストのネットワーキング

{
  "mcpServers": {
    "earthdata": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--network=host",
        "-e", "EARTHDATA_USERNAME",
        "-e", "EARTHDATA_PASSWORD",
        "datalayer/earthdata-mcp-server:latest"
      ],
      "env": {
        "EARTHDATA_USERNAME": "your_username",
        "EARTHDATA_PASSWORD": "your_password"
      }
    }
  }
}

ツール

earthdata ツールセットは 3 つのツールを提供します。いずれも認証情報を必要としません。ただし、mode="download" の download_earth_data_granules は NASA Earthdata Login を必要とします。デフォルトの manifest モードと script モードは匿名で動作します。

search_earth_datasets

• NASA Earthdata でデータセットを検索します。
• 入力:
  • search_keywords (str): データセットのタイトル内で検索するキーワード。
  • count (int): 返すデータセットの数。
  • temporal (tuple): (オプション) (date_from, date_to) 形式の時間範囲。
  • bounding_box (tuple): (オプション) (lower_left_lon, lower_left_lat, upper_right_lon, upper_right_lat) 形式のバウンディングボックス。
• 戻り値: データセットの概要のリスト。

search_earth_datagranules

• NASA Earthdata でデータグラニュールを検索します。
• 入力:
  • short_name (str): データセットのショートネーム。
  • count (int): 返すデータグラニュールの数。
  • temporal (tuple): (オプション) (date_from, date_to) 形式の時間範囲。
  • bounding_box (tuple): (オプション) (lower_left_lon, lower_left_lat, upper_right_lon, upper_right_lat) 形式のバウンディングボックス。
• 戻り値: データグラニュールのリスト。

download_earth_data_granules

• 明示的なモードを指定して、グラニュールの検索とオプションのダウンロードを行います。
• 認証: NASA Earthdata のログイン認証情報が必要なのは mode="download" のみです（認証ガイドを参照）。manifest モードと script モードは匿名で動作します。
• 入力:
  • folder_name (str): データを保存するローカルフォルダー名。
  • short_name (str): ダウンロードする Earth データセットのショートネーム。
  • count (int): ダウンロードするデータグラニュールの数。
  • temporal (tuple): (オプション) (date_from, date_to) 形式の期間。
  • bounding_box (tuple): (オプション) (lower_left_lon, lower_left_lat, upper_right_lon, upper_right_lat) 形式のバウンディングボックス。
  • mode (str): 次のいずれか:
    • manifest: グラニュールのメタデータのみを返します。
    • download: サーバー側で直接ファイルをダウンロードします。
    • script: 別の場所で実行する Python コードを返します。
  • max_manifest_items (int): manifest モードで返される項目の最大数。

ダウンロードの仕組み

download_earth_data_granules は常に、指定したフィルターでグラニュールを検索することから始まり、その後 mode に応じて動作します:

1. manifest
   • ID、タイトル、リンクを含む構造化されたプレビュー（items）を返します。
   • ファイルは書き込みません。
   • クエリの範囲を検証するための最適な最初のステップです。
2. download
   • 環境の認証情報を使用して Earthdata で認証します。
   • 一致するグラニュールをサーバーのランタイム上の folder_name に直接ダウンロードします。
   • ダウンロードされたファイルパスを返します。
3. script
   • 同じ検索 + ダウンロードを実行する実行可能な Python コードを返します。
   • 別の MCP サーバーが制御するノートブック/ランタイムで実行する場合に最適なオプションです。

推奨されるダウンロード戦略

1. まず mode="manifest" を使用して、安全に結果を確認します。
2. mcp-compose + jupyter-mcp-server を介したノートブック駆動の実行を行う場合は、mode="script" を使用します。
3. サーバー側でのファイル書き込みを意図している場合にのみ、mode="download" を使用します。

mcp-compose を使用した完全なコンポジション例については、ダウンロードワークフローのドキュメントを参照してください。

プロンプト

1. download_analyze_global_sea_level

   • script モードの download_earth_data_granules から始まるワークフローを生成します。
   • コンポジションされたノートブック/ランタイムスタック（mcp-compose 経由）で実行することを意図しています。

2. sealevel_rise_dataset

   • 世界中の海面上昇に関連するデータセットを検索します。
   • 入力:
     • start_year (int): 対象とする開始年。
     • end_year (int): 対象とする終了年。
   • 戻り値: 正しくフォーマットされたプロンプト。

3. ask_datasets_format

   • データセットのフォーマットについて質問するためのものです。
   • 戻り値: 正しくフォーマットされたプロンプト。

開発

make dev    # editable install with the test, lint and typing extras
make test
make lint

リリースはタグをプッシュすることで作成されます。RELEASE.mdを参照してください。

ビルド

# or run `docker build -t datalayer/earthdata-mcp-server .`
make build-docker

必要に応じて、ビルド済みイメージをプルすることもできます。

make pull-docker