earthdata-mcp-server 0.3.0

No project description provided

🪐 ✨ Earthdata MCP Server

Earthdata MCP Server is a Model Context Protocol (MCP) server implementation that provides tools to interact with NASA Earth Data. It enables efficient dataset discovery and retrieval for Geospatial analysis.

🚀 NEW: This server now includes all Jupyter MCP Server tools through composition, providing a unified interface for both Earth data discovery and Jupyter notebook manipulation. All Jupyter MCP Server command-line options are also available for seamless integration.

🚀 Key Features

• Unified Interface: Combines Earthdata and Jupyter tools
• Efficient Data Retrieval: Search and download Earthdata datasets

The following demo uses this MCP server to search for datasets and data granules on NASA Earthdata, to download the data in Jupyter and to run further analysis.

Analyzing Sea Level Rise with AI-Powered Geospatial Tools and Jupyter - Watch Video

🏁 Getting Started

For comprehensive setup instructions—including Streamable HTTP transport and advanced configuration—check out thr documentation. Or, get started quickly with JupyterLab and stdio transport here below.

1. Set Up Your Environment

pip install jupyterlab==4.4.1 jupyter-collaboration==4.0.2 ipykernel
pip uninstall -y pycrdt datalayer_pycrdt
pip install datalayer_pycrdt==0.12.17

2. Start JupyterLab

# make jupyterlab
jupyter lab --port 8888 --IdentityProvider.token MY_TOKEN --ip 0.0.0.0

3. Configure Your Preferred MCP Client

[!NOTE]

Ensure the port of the DOCUMENT_URL and RUNTIME_URL match those used in the jupyter lab command.

The DOCUMENT_ID which is the path to the notebook you want to connect to, should be relative to the directory where JupyterLab was started.

In a basic setup, DOCUMENT_URL and RUNTIME_URL are the same. DOCUMENT_TOKEN, and RUNTIME_TOKEN are also the same and is actually the Jupyter Token.

MacOS and Windows

{
  "mcpServers": {
    "earthdata": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "DOCUMENT_URL",
        "-e",
        "DOCUMENT_TOKEN",
        "-e",
        "DOCUMENT_ID",
        "-e",
        "RUNTIME_URL",
        "-e",
        "RUNTIME_TOKEN",
        "datalayer/earthdata-mcp-server:latest"
      ],
      "env": {
        "DOCUMENT_URL": "http://host.docker.internal:8888",
        "DOCUMENT_TOKEN": "MY_TOKEN",
        "DOCUMENT_ID": "notebook.ipynb",
        "RUNTIME_URL": "http://host.docker.internal:8888",
        "RUNTIME_TOKEN": "MY_TOKEN"
      }
    }
  }
}

Linux

{
  "mcpServers": {
    "earthdata": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "DOCUMENT_URL",
        "-e",
        "DOCUMENT_TOKEN",
        "-e",
        "DOCUMENT_ID",
        "-e",
        "RUNTIME_URL",
        "-e",
        "RUNTIME_TOKEN",
        "--network=host",
        "datalayer/earthdata-mcp-server:latest"
      ],
      "env": {
        "DOCUMENT_URL": "http://localhost:8888",
        "DOCUMENT_TOKEN": "MY_TOKEN",
        "DOCUMENT_ID": "notebook.ipynb",
        "RUNTIME_URL": "http://localhost:8888",
        "RUNTIME_TOKEN": "MY_TOKEN"
      }
    }
  }
}

Connecting to NASA Earthdata

To interact with NASA Earthdata, you need an Earthdata Login account. You can learn more and register for an account through the Earthdata Login API portal.

Authentication

This server uses your Earthdata Login credentials to authenticate with NASA Earthdata. You need to provide your username and password as environment variables. Generate and Earth data Token in one of the tabs.

In your terminal, you can set them like this:

export EARTHDATA_USERNAME="your_username"
export EARTHDATA_PASSWORD="your_password"
export EARTHDATA_TOKEN="your_token"

The server will automatically use these variables to authenticate your requests.

📚 Documentation

• Architecture: Learn about the server composition pattern
• Authentication: How to authenticate with NASA Earthdata
• Tools: Detailed documentation of available tools

Tools

The server offers 15 tools total: 3 Earthdata-specific tools plus 12 Jupyter notebook manipulation tools (prefixed with jupyter_).

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

• Download Earth data granules from NASA Earth Data and integrate with Jupyter notebooks.
• This tool combines earthdata search capabilities with jupyter notebook manipulation to create a seamless download workflow.
• Authentication: Requires NASA Earthdata Login credentials (see Authentication section)
• 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).
• Returns: Success message with download code preparation details.

Jupyter Tools (Composed)

The following Jupyter notebook manipulation tools are available with the jupyter_ prefix:

• jupyter_append_markdown_cell: Add markdown cells to notebooks
• jupyter_insert_markdown_cell: Insert markdown cells at specific positions
• jupyter_overwrite_cell_source: Modify existing cell content
• jupyter_append_execute_code_cell: Add and execute code cells
• jupyter_insert_execute_code_cell: Insert and execute code cells at specific positions
• jupyter_execute_cell_with_progress: Execute cells with progress monitoring
• jupyter_execute_cell_simple_timeout: Execute cells with timeout
• jupyter_execute_cell_streaming: Execute cells with streaming output
• jupyter_read_all_cells: Read all notebook cells
• jupyter_read_cell: Read specific notebook cells
• jupyter_get_notebook_info: Get notebook metadata
• jupyter_delete_cell: Delete notebook cells

For detailed documentation of the Jupyter tools, see the Jupyter MCP Server documentation.

Prompts

1. download_analyze_global_sea_level 🆕

   • Generate a comprehensive workflow for downloading and analyzing Global Mean Sea Level Trend dataset.
   • Uses both earthdata download tools and jupyter analysis capabilities.
   • Returns: Detailed prompt for complete sea level analysis workflow.

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