<!--
~ Copyright (c) 2023-2024 Datalayer, Inc.
~
~ BSD 3-Clause License
-->

🪐 ✨ Earthdata MCP Server

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

This server is intentionally Earthdata-only.

If you need notebook/runtime tools, compose this server 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

<div>
<a href="https://www.loom.com/share/c2b5b05f548d4f1492d5c107f0c48dbc">
<p>Analyzing Sea Level Rise with AI-Powered Geospatial Tools and Jupyter - Watch Video</p>
</a>
<a href="https://www.loom.com/share/c2b5b05f548d4f1492d5c107f0c48dbc">

</a>
</div>

Getting Started

Local install

pip install earthdata-mcp-server

Docker with Claude Desktop

{
  "mcpServers": {
    "earthdata": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "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",
        "datalayer/earthdata-mcp-server:latest"
      ],
      "env": {
        "EARTHDATA_USERNAME": "your_username",
        "EARTHDATA_PASSWORD": "your_password"
      }
    }
  }
}

Tools

The server offers 3 Earthdata tools.

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: Requires NASA Earthdata Login credentials (see authentication guide)
- 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.

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