Earthdata MCP Server

🪐 ✨ Earthdata MCP Server

O Earthdata MCP Server é uma implementação de servidor Model Context Protocol (MCP) que fornece ferramentas para interagir com NASA Earth Data.

Ele é construído como uma extensão reactor_mcp_server, portanto funciona de duas maneiras:

• Por conta própria: earthdata-mcp-server start serve as ferramentas Earthdata e nada mais, via stdio ou HTTP transmissível.
• Como um conjunto de ferramentas: instalado ao lado de qualquer host reactor_mcp_server, ele é descoberto e servido como o conjunto de ferramentas opcional earthdata para um cliente que o solicitar: /mcp?earthdata. O Datalayer MCP Server o serve dessa forma, ao lado de notebooks e sandboxes.

O servidor é intencionalmente exclusivo para Earthdata. Para ferramentas de notebook e runtime, sirva-o ao lado delas em um único host, ou componha-o com jupyter-mcp-server usando mcp-compose.

Principais Recursos

• Descoberta de conjuntos de dados na NASA Earthdata
• Busca de grânulos com filtros temporais e de caixa delimitadora
• Fluxo de download flexível com modos de execução explícitos

Começando

Instalação 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

Opção	Ambiente	Padrão
--transport	TRANSPORT	stdio (ou streamable-http)
--host	HOST	0.0.0.0
--port	PORT	4040

Como um conjunto de ferramentas em um host MCP reator

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

Um cliente conectando-se a http://localhost:4040/mcp?earthdata obtém as ferramentas Earthdata ao lado de qualquer outra coisa instalada; /toolsets lista o que o host oferece. Em 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) serve o conjunto de ferramentas para um cliente que não nomeia nenhum.

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

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

Ferramentas

O conjunto de ferramentas earthdata oferece 3 ferramentas. Nenhuma delas precisa de credenciais, exceto download_earth_data_granules em mode="download", que precisa de um NASA Earthdata Login. Seu modo padrão manifest e seu modo script funcionam anonimamente.

search_earth_datasets

• Busca por conjuntos de dados na NASA Earthdata.
• Entrada:
  • search_keywords (str): Palavras-chave para buscar nos títulos dos conjuntos de dados.
  • count (int): Número de conjuntos de dados a retornar.
  • temporal (tuple): (Opcional) Intervalo temporal no formato (date_from, date_to).
  • bounding_box (tuple): (Opcional) Caixa delimitadora no formato (lower_left_lon, lower_left_lat, upper_right_lon, upper_right_lat).
• Retorna: Lista de resumos de conjuntos de dados.

search_earth_datagranules

• Busca por grânulos de dados na NASA Earthdata.
• Entrada:
  • short_name (str): Nome curto do conjunto de dados.
  • count (int): Número de grânulos de dados a retornar.
  • temporal (tuple): (Opcional) Intervalo temporal no formato (date_from, date_to).
  • bounding_box (tuple): (Opcional) Caixa delimitadora no formato (lower_left_lon, lower_left_lat, upper_right_lon, upper_right_lat).
• Retorna: Lista de grânulos de dados.

download_earth_data_granules

• Busca e opcionalmente baixa grânulos com modos explícitos.
• Autenticação: Apenas mode="download" precisa de credenciais NASA Earthdata Login (veja o guia de autenticação); os modos manifest e script funcionam anonimamente.
• Entrada:
  • folder_name (str): Nome da pasta local para salvar os dados.
  • short_name (str): Nome curto do conjunto de dados da Terra a baixar.
  • count (int): Número de grânulos de dados a baixar.
  • temporal (tuple): (Opcional) Intervalo temporal no formato (date_from, date_to).
  • bounding_box (tuple): (Opcional) Caixa delimitadora no formato (lower_left_lon, lower_left_lat, upper_right_lon, upper_right_lat).
  • mode (str): Um de:
    • manifest: Retorna apenas metadados dos grânulos.
    • download: Baixa arquivos diretamente no lado do servidor.
    • script: Retorna código Python para executar em outro lugar.
  • max_manifest_items (int): Máximo de itens retornados no modo manifest.

Como funciona o download

download_earth_data_granules sempre começa buscando grânulos com seus filtros, depois se comporta com base em mode:

1. manifest
   • Retorna uma prévia estruturada (items) com IDs, títulos e links.
   • Não grava arquivos.
   • Melhor primeiro passo para validar o escopo da consulta.
2. download
   • Autentica com Earthdata usando credenciais de ambiente.
   • Baixa grânulos correspondentes diretamente para folder_name no runtime do servidor.
   • Retorna caminhos dos arquivos baixados.
3. script
   • Retorna código Python executável que realiza a mesma busca + download.
   • Melhor opção quando a execução deve ocorrer em um notebook/runtime controlado por outro servidor MCP.

Estratégia de download recomendada

1. Use mode="manifest" primeiro para inspecionar resultados com segurança.
2. Use mode="script" quando quiser execução orientada por notebook via mcp-compose + jupyter-mcp-server.
3. Use mode="download" apenas quando gravações de arquivos no lado do servidor forem pretendidas.

Para um exemplo completo de composição com mcp-compose, veja a documentação do fluxo de download.

Prompts

1. download_analyze_global_sea_level

   • Gera um fluxo de trabalho que começa com download_earth_data_granules no modo script.
   • Destinado a ser executado em uma pilha composta de notebook/runtime (via mcp-compose).

2. sealevel_rise_dataset

   • Busca por conjuntos de dados relacionados à elevação do nível do mar em todo o mundo.
   • Entrada:
     • start_year (int): Ano inicial a considerar.
     • end_year (int): Ano final a considerar.
   • Retorna: Prompt formatado corretamente.

3. ask_datasets_format

   • Para perguntar sobre o formato dos conjuntos de dados.
   • Retorna: Prompt formatado corretamente.

Desenvolvimento

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

As versões são cortadas ao enviar uma tag; veja RELEASE.md.

Construção

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

Se preferir, você pode puxar as imagens pré-construídas.

make pull-docker