Earthdata MCP Server

🪐 ✨ Earthdata MCP Server

Earthdata MCP Server es una implementación de servidor del Model Context Protocol (MCP) que proporciona herramientas para interactuar con NASA Earth Data.

Está construido como una extensión de reactor_mcp_server, por lo que funciona de dos maneras:

• Por sí solo: earthdata-mcp-server start sirve las herramientas de Earthdata y nada más, a través de stdio o HTTP transmisible.
• Como conjunto de herramientas: instalado junto a cualquier host de reactor_mcp_server, se descubre y se sirve como el conjunto de herramientas opcional earthdata a un cliente que lo solicite: /mcp?earthdata. El Datalayer MCP Server lo sirve de esta manera, junto a notebooks y sandboxes.

El servidor está intencionalmente limitado solo a Earthdata. Para herramientas de notebook y runtime, sírvelo junto a ellas en un solo host, o compónlo con jupyter-mcp-server usando mcp-compose.

Características principales

• Descubrimiento de conjuntos de datos en NASA Earthdata
• Búsqueda de gránulos con filtros temporales y de cuadro delimitador
• Flujo de trabajo de descarga flexible con modos de ejecución explícitos

Primeros pasos

Instalación local

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

Opción	Entorno	Predeterminado
--transport	TRANSPORT	stdio (o streamable-http)
--host	HOST	0.0.0.0
--port	PORT	4040

Como conjunto de herramientas en un host MCP reactor

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

Un cliente que se conecta a http://localhost:4040/mcp?earthdata obtiene las herramientas de Earthdata junto a lo que sea que esté instalado; /toolsets lista lo que ofrece el host. En código:

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) sirve el conjunto de herramientas a un cliente que no nombre ninguna.

Docker con 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"
      }
    }
  }
}

Red de host 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"
      }
    }
  }
}

Herramientas

El conjunto de herramientas earthdata ofrece 3 herramientas. Ninguna de ellas necesita credenciales, excepto download_earth_data_granules en mode="download", que necesita un inicio de sesión de NASA Earthdata. Su modo manifest predeterminado y su modo script funcionan de forma anónima.

search_earth_datasets

• Busca conjuntos de datos en NASA Earthdata.
• Entrada:
  • search_keywords (str): Palabras clave para buscar en los títulos de los conjuntos de datos.
  • count (int): Número de conjuntos de datos a devolver.
  • temporal (tuple): (Opcional) Rango temporal en el formato (date_from, date_to).
  • bounding_box (tuple): (Opcional) Cuadro delimitador en el formato (lower_left_lon, lower_left_lat, upper_right_lon, upper_right_lat).
• Devuelve: Lista de resúmenes de conjuntos de datos.

search_earth_datagranules

• Busca gránulos de datos en NASA Earthdata.
• Entrada:
  • short_name (str): Nombre corto del conjunto de datos.
  • count (int): Número de gránulos de datos a devolver.
  • temporal (tuple): (Opcional) Rango temporal en el formato (date_from, date_to).
  • bounding_box (tuple): (Opcional) Cuadro delimitador en el formato (lower_left_lon, lower_left_lat, upper_right_lon, upper_right_lat).
• Devuelve: Lista de gránulos de datos.

download_earth_data_granules

• Busca y opcionalmente descarga gránulos con modos explícitos.
• Autenticación: Solo mode="download" necesita credenciales de inicio de sesión de NASA Earthdata (consulta la guía de autenticación); los modos manifest y script funcionan de forma anónima.
• Entrada:
  • folder_name (str): Nombre de la carpeta local para guardar los datos.
  • short_name (str): Nombre corto del conjunto de datos de Earthdata a descargar.
  • count (int): Número de gránulos de datos a descargar.
  • temporal (tuple): (Opcional) Rango temporal en el formato (date_from, date_to).
  • bounding_box (tuple): (Opcional) Cuadro delimitador en el formato (lower_left_lon, lower_left_lat, upper_right_lon, upper_right_lat).
  • mode (str): Uno de:
    • manifest: Devuelve solo metadatos de gránulos.
    • download: Descarga archivos directamente en el lado del servidor.
    • script: Devuelve código Python para ejecutar en otro lugar.
  • max_manifest_items (int): Máximo de elementos devueltos en el modo manifest.

Cómo funciona la descarga

download_earth_data_granules siempre comienza buscando gránulos con tus filtros, luego se comporta según mode:

1. manifest
   • Devuelve una vista previa estructurada (items) con IDs, títulos y enlaces.
   • No escribe archivos.
   • Mejor primer paso para validar el alcance de la consulta.
2. download
   • Se autentica con Earthdata usando credenciales de entorno.
   • Descarga los gránulos coincidentes directamente a folder_name en el runtime del servidor.
   • Devuelve las rutas de los archivos descargados.
3. script
   • Devuelve código Python ejecutable que realiza la misma búsqueda + descarga.
   • Mejor opción cuando la ejecución debe ocurrir en un notebook/runtime controlado por otro servidor MCP.

Estrategia de descarga recomendada

1. Usa mode="manifest" primero para inspeccionar los resultados de forma segura.
2. Usa mode="script" cuando quieras ejecución impulsada por notebook a través de mcp-compose + jupyter-mcp-server.
3. Usa mode="download" solo cuando se pretendan escrituras de archivos en el lado del servidor.

Para un ejemplo completo de composición con mcp-compose, consulta la documentación del flujo de trabajo de descarga.

Prompts

1. download_analyze_global_sea_level

   • Genera un flujo de trabajo que comienza con download_earth_data_granules en modo script.
   • Diseñado para ejecutarse en una pila compuesta de notebook/runtime (a través de mcp-compose).

2. sealevel_rise_dataset

   • Busca conjuntos de datos relacionados con el aumento del nivel del mar en todo el mundo.
   • Entrada:
     • start_year (int): Año de inicio a considerar.
     • end_year (int): Año de fin a considerar.
   • Devuelve: Prompt correctamente formateado.

3. ask_datasets_format

   • Para preguntar sobre el formato de los conjuntos de datos.
   • Devuelve: Prompt correctamente formateado.

Desarrollo

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

Los lanzamientos se realizan empujando una etiqueta; consulta RELEASE.md.

Construcción

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

Si lo prefieres, puedes extraer las imágenes preconstruidas.

make pull-docker