--- slug: "earthdata-mcp-server" source_type: "readme" source_url: "https://cdn.jsdelivr.net/gh/datalayer/earthdata-mcp-server@main/README.md" repo: "https://github.com/datalayer/earthdata-mcp-server" source_file: "README.md" branch: "main" --- [![Datalayer](https://assets.datalayer.tech/datalayer-25.svg)](https://datalayer.io) [![Become a Sponsor](https://img.shields.io/static/v1?label=Become%20a%20Sponsor&message=%E2%9D%A4&logo=GitHub&style=flat&color=1ABC9C)](https://github.com/sponsors/datalayer) # 🪐 ✨ Earthdata MCP Server [![PyPI - Version](https://img.shields.io/pypi/v/earthdata-mcp-server)](https://pypi.org/project/earthdata-mcp-server) [![smithery badge](https://smithery.ai/badge/@datalayer/earthdata-mcp-server)](https://smithery.ai/server/@datalayer/earthdata-mcp-server) [![Unit Tests](https://github.com/datalayer/earthdata-mcp-server/actions/workflows/tests.yml/badge.svg)](https://github.com/datalayer/earthdata-mcp-server/actions/workflows/tests.yml) [![Lint and Type Check](https://github.com/datalayer/earthdata-mcp-server/actions/workflows/lint.yml/badge.svg)](https://github.com/datalayer/earthdata-mcp-server/actions/workflows/lint.yml) Earthdata MCP Server is a [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) server implementation that provides tools to interact with [NASA Earth Data](https://www.earthdata.nasa.gov/). This server is intentionally Earthdata-only. If you need notebook/runtime tools, compose this server with `jupyter-mcp-server` using [mcp-compose](https://github.com/datalayer/mcp-compose). ## Key Features - Dataset discovery on NASA Earthdata - Granule search with temporal and bounding box filters - Flexible download workflow with explicit execution modes

Analyzing Sea Level Rise with AI-Powered Geospatial Tools and Jupyter - Watch Video
## Getting Started ### Local install ```bash pip install earthdata-mcp-server ``` ### Docker with Claude Desktop ```json { "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 ```json { "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](https://github.com/datalayer/earthdata-mcp-server/blob/HEAD/docs/authentication.md)) - 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](https://github.com/datalayer/earthdata-mcp-server/blob/HEAD/docs/download.md). ## 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 ```bash # or run `docker build -t datalayer/earthdata-mcp-server .` make build-docker ``` If you prefer, you can pull the prebuilt images. ```bash make pull-docker ```