earthdata-mcp-server

🪐 ✨ Earthdata MCP Server

Earthdata MCP Server is a Model Context Protocol (MCP) server implementation that provides tools to interact with NASA Earth Data.

It is built as a reactor_mcp_server extension, so it runs two ways:

• On its own: earthdata-mcp-server start serves the Earthdata tools and nothing else, over stdio or streamable HTTP.
• As a toolset: installed beside any reactor_mcp_server host, it is discovered and served as the opt-in earthdata toolset to a client that asks for it: /mcp?earthdata. The Datalayer MCP Server serves it this way, next to notebooks and sandboxes.

The server is intentionally Earthdata-only. For notebook and runtime tools, serve it beside them on one host, or compose it with jupyter-mcp-server using mcp-compose.

Key Features

• Dataset discovery on NASA Earthdata
• Granule search with temporal and bounding box filters
• Flexible download workflow with explicit execution modes

Getting Started

Local install

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

Option	Environment	Default
--transport	TRANSPORT	stdio (or streamable-http)
--host	HOST	0.0.0.0
--port	PORT	4040

As a toolset on a reactor MCP host

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

A client connecting to http://localhost:4040/mcp?earthdata gets the Earthdata tools beside whatever else is installed; /toolsets lists what the host offers. In code:

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) serves the toolset to a client that names none.

Docker with Claude Desktop

{
  "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 host networking

{
  "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"
      }
    }
  }
}

Tools

The earthdata toolset offers 3 tools. None of them needs credentials, except download_earth_data_granules in mode="download", which needs a NASA Earthdata Login. Its default manifest mode and its script mode work anonymously.

search_earth_datasets

• Search for datasets on NASA Earthdata.
• Input:
  • search_keywords (str): Keywords to search for in the dataset titles.
  • count (int): Number of datasets to return.
  • temporal (tuple): (Optional) Temporal range in the format (date_from, date_to).
  • bounding_box (tuple): (Optional) Bounding box in the format (lower_left_lon, lower_left_lat, upper_right_lon, upper_right_lat).
• Returns: List of dataset abstracts.

search_earth_datagranules

• Search for data granules on NASA Earthdata.
• Input:
  • short_name (str): Short name of the dataset.
  • count (int): Number of data granules to return.
  • temporal (tuple): (Optional) Temporal range in the format (date_from, date_to).
  • bounding_box (tuple): (Optional) Bounding box in the format (lower_left_lon, lower_left_lat, upper_right_lon, upper_right_lat).
• Returns: List of data granules.

download_earth_data_granules

• Search and optionally download granules with explicit modes.
• Authentication: Only mode="download" needs NASA Earthdata Login credentials (see authentication guide); manifest and script modes work anonymously.
• Input:
  • folder_name (str): Local folder name to save the data.
  • short_name (str): Short name of the Earth dataset to download.
  • count (int): Number of data granules to download.
  • temporal (tuple): (Optional) Temporal range in the format (date_from, date_to).
  • bounding_box (tuple): (Optional) Bounding box in the format (lower_left_lon, lower_left_lat, upper_right_lon, upper_right_lat).
  • mode (str): One of:
    • manifest: Returns granule metadata only.
    • download: Downloads files directly on server side.
    • script: Returns Python code to execute elsewhere.
  • max_manifest_items (int): Max items returned in manifest mode.

How download works

download_earth_data_granules always starts by searching for granules with your filters, then behaves based on mode:

1. manifest
   • Returns a structured preview (items) with IDs, titles, and links.
   • Does not write files.
   • Best first step for validating query scope.
2. download
   • Authenticates with Earthdata using environment credentials.
   • Downloads matching granules directly to folder_name on the server runtime.
   • Returns downloaded file paths.
3. script
   • Returns executable Python code that performs the same search + download.
   • Best option when execution should happen in a notebook/runtime controlled by another MCP server.

Recommended download strategy

1. Use mode="manifest" first to inspect results safely.
2. Use mode="script" when you want notebook-driven execution via mcp-compose + jupyter-mcp-server.
3. Use mode="download" only when server-side file writes are intended.

For a full composition example with mcp-compose, see download workflow docs.

Prompts

1. download_analyze_global_sea_level

   • Generates a workflow that starts with download_earth_data_granules in script mode.
   • Intended to be executed in a composed notebook/runtime stack (via mcp-compose).

2. sealevel_rise_dataset

   • Search for datasets related to sea level rise worldwide.
   • Input:
     • start_year (int): Start year to consider.
     • end_year (int): End year to consider.
   • Returns: Prompt correctly formatted.

3. ask_datasets_format

   • To ask about the format of the datasets.
   • Returns: Prompt correctly formatted.

Development

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

Releases are cut by pushing a tag; see RELEASE.md.

Building

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

If you prefer, you can pull the prebuilt images.

make pull-docker