🪐 ✨ Earthdata MCP Server

🪐 ✨ Earthdata MCP 服务

Earthdata MCP 服务是一个 Model Context Protocol (MCP) 服务实现，提供与 NASA Earth Data 交互的工具。

它作为 reactor_mcp_server 扩展构建，因此有两种运行方式：

• 独立运行：earthdata-mcp-server start 只提供 Earthdata 工具，通过 stdio 或可流式 HTTP 提供服务。
• 作为工具集：安装在任何 reactor_mcp_server 宿主旁边，它会被发现，并作为可选启用的 earthdata 工具集提供给请求它的客户端：/mcp?earthdata。Datalayer MCP 服务就是这样提供它的，与 notebook 和沙箱并列。

该服务刻意只面向 Earthdata。对于 notebook 和运行时工具，请在同一宿主上与它们一起提供，或使用 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

• 使用明确的模式搜索并可选下载 granule。
• 身份验证：只有 mode="download" 需要 NASA Earthdata Login 凭据（参见身份验证指南）；manifest 和 script 模式可匿名使用。
• 输入：
  • folder_name (str)：用于保存数据的本地文件夹名称。
  • short_name (str)：要下载的地球数据集的短名称。
  • count (int)：要下载的数据 granule 数量。
  • temporal (tuple)：（可选）时间范围，格式为 (date_from, date_to)。
  • bounding_box (tuple)：（可选）边界框，格式为 (lower_left_lon, lower_left_lat, upper_right_lon, upper_right_lat)。
  • mode (str)：以下之一：
    • manifest：仅返回 granule 元数据。
    • download：直接在服务端下载文件。
    • script：返回可在其他地方执行的 Python 代码。
  • max_manifest_items (int)：manifest 模式下返回的最大条目数。

下载的工作原理

download_earth_data_granules 总是先使用你的筛选条件搜索 granule，然后根据 mode 执行相应操作：

1. manifest
   • 返回结构化预览（items），包含 ID、标题和链接。
   • 不写入文件。
   • 用于验证查询范围的最佳第一步。
2. download
   • 使用环境凭据向 Earthdata 进行身份验证。
   • 将匹配的 granule 直接下载到服务端运行时的 folder_name。
   • 返回已下载文件的路径。
3. script
   • 返回可执行的 Python 代码，执行相同的搜索 + 下载。
   • 当执行应在由另一个 MCP 服务控制的 notebook/运行时中进行时，这是最佳选择。

推荐的下载策略

1. 首先使用 mode="manifest" 安全地检查结果。
2. 当你希望通过 mcp-compose + jupyter-mcp-server 实现 notebook 驱动的执行时，使用 mode="script"。
3. 仅当确实要在服务端写入文件时，才使用 mode="download"。

有关使用 mcp-compose 的完整组合示例，请参见下载工作流文档。

提示词

1. download_analyze_global_sea_level

   • 生成一个工作流，以 script 模式下的 download_earth_data_granules 开始。
   • 旨在在组合的 notebook/运行时栈中执行（通过 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

发布通过推送 tag 来创建；参见 RELEASE.md。

构建

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

如果你愿意，也可以拉取预构建的镜像。

make pull-docker