MapBiomas Soil MCP
Provides tools for querying soil data products, planning and executing GEE recipes for texture and carbon modeling, monitoring Earth Engine tasks, and visualizing output rasters.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MapBiomas Soil MCPWhat's the average clay content in the state of São Paulo?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MapBiomas Soil MCP
Em resumo: este projeto permite consultar dados de solo, planejar receitas, executar processamentos autorizados no Google Earth Engine (GEE), acompanhar tarefas e fazer perguntas sobre os resultados — sem baixar os mapas nacionais para o computador.
📘 Para uma explicação visual, sem pressupor conhecimento técnico, veja arquitetura-gee-mcp.html.
O que você pode fazer
Objetivo | Primeiro passo | Altera dados? |
Perguntar sobre um produto de solo já publicado | Consultar pelo MCP | Não |
Entender a ordem de uma modelagem | Planejar uma receita | Não |
Prever textura ou carbono | Rodar um teste pequeno e autorizado | Sim, cria tarefas no GEE |
Preparar tabelas que antes usavam R | Planejar uma etapa Python local | Não no planejamento |
Consultar um resultado que você já produziu | Informar o run_id e a camada | Não |
Regra de ouro: consultar e planejar são operações de leitura. Executar uma receita cria tarefas no GEE e só deve acontecer após revisar os assets, a área, a pasta de saída e os custos esperados.
Related MCP server: GeoSight MCP Server
O problema que esta arquitetura resolve
Mapas nacionais de solo têm muitos pixels, profundidades, anos, imagens de satélite e tabelas de amostras. Guardar e recalcular tudo em um computador comum seria lento, caro e difícil de manter.
Por isso o projeto usa uma arquitetura híbrida:
Dados tabulares locais
↓
Python local: preparação e validação
↓
GEE: modelos, mapas e tarefas pesadas
↓
Assets versionados por execução
↓
MCP: perguntas, métricas, mapas e monitoramentoEm linguagem simples:
Google Earth Engine (GEE): plataforma em nuvem onde ficam imagens, coleções e processamento espacial em grande escala. É onde o cálculo pesado acontece.
Python local: código que roda no computador para organizar tabelas, preparar dados e validar resultados.
MCP: ponte controlada entre a conversa e as ferramentas. Ele permite que o assistente planeje, execute quando autorizado, acompanhe tasks e consulte resultados.
run_id: nome único de uma execução. Ele separa os resultados de um teste dos resultados de outro.
O projeto não tenta copiar os rasters do Brasil, nem recriar o banco do GEE no computador. Dados espaciais grandes continuam no GEE; localmente ficam código, tabelas, configurações, validações e resultados compactos quando necessários.
De onde veio a lógica do projeto
A pasta soil_30m_landsat foi preservada como referência científica e de auditoria. Ela contém scripts, notebooks e a sequência de etapas do fluxo original de solo.
Pense nela como uma receita: ela informa ingredientes, ordem de preparo, filtros, fórmulas, modelos e verificações. Este projeto adapta essa lógica para Python e MCP.
Referência original | O que foi adaptado | Por que |
Scripts/notebooks de textura no GEE | Receitas Python que montam planos e tasks no GEE | Rodar o cálculo perto dos dados espaciais |
Scripts/notebooks de carbono no GEE | Receitas Python para matriz, réplicas e previsão anual | Permitir previsões controladas e monitoráveis |
Scripts soildata/*.R | Etapas Python locais com entradas e saídas declaradas | Não depender de abrir scripts R manualmente |
Passos manuais | Etapas nomeadas, planejáveis e auditáveis | Facilitar revisão e rastreabilidade |
Saídas soltas | Caminhos abaixo de runs/<run_id>/... | Saber qual execução produziu cada mapa |
O que não foi copiado:
dados privados, credenciais ou permissões de terceiros;
assets nacionais para o computador;
permissões da MapBiomas ou de qualquer outra organização;
o namespace oficial de saída de outra equipe.
O MCP usa as permissões da conta autenticada. Ele não cria acesso e não contorna bloqueios de dados privados.
O que já está disponível
Consultas, mapas e monitoramento
Produtos MapBiomas Solo Collection 3: areia, silte, argila, grupo/subgrupo/classe textural e profundidade até pedregosidade.
Estatísticas para uma área ou ponto: média, mediana, mínimo, máximo, desvio padrão e, para classes, moda.
Mapa nacional das camadas C03 publicadas, em PNG estático ou no visualizador interativo, recortado no limite do Brasil.
Consulta de uma banda produzida pelo seu próprio run_id.
URL de thumbnail/mapa para uma banda produzida.
Visualizador local interativo para uma a seis camadas produzidas pelo seu próprio run_id.
Listagem e consulta de status de tarefas Earth Engine.
Receitas GEE
Receita | Resultado principal | Precisa de |
texture_training_matrix | Matriz de treinamento para textura | Pontos de solo e covariáveis autorizadas |
texture_prediction | Areia, silte, argila e cascalho por profundidade | Matriz de treinamento |
texture_classification | Grupo, subgrupo e classe textural | Predição de textura |
texture_density | Densidade da terra fina e rocha | Textura e geologia |
texture_stoniness | Pedregosidade e profundidades de 50%/90% | Textura e densidade |
carbon_training_matrix | Matriz de treinamento SOC | Pontos de carbono autorizados |
carbon_temporal_replication | Réplicas temporais de amostras estáveis | Pontos ou matriz SOC |
carbon_prediction | Série anual de carbono, 1985–2024 | Matriz de carbono |
Etapas que eram R, agora em Python
A cadeia local possui etapas para juntar e limpar tabelas, preparar covariáveis, transformar composição PSD/ALR, estimar densidade e estoque de carbono, calcular estatísticas, treinar e validar modelos.
Use list_soildata_pipeline para ver a lista completa e o estado de cada etapa. Algumas portas são diretas; outras são aproximações que precisam ser validadas contra os dados reais.
Pré-requisitos
Antes de iniciar, confirme:
Python 3.11 a 3.14 e Poetry instalados.
Uma conta Google autorizada a usar Earth Engine.
Um projeto Google Cloud registrado/configurado para Earth Engine.
Permissão de leitura nos assets necessários para a receita desejada.
Permissão de escrita em uma coleção GEE própria, se for exportar resultados.
Para etapas locais, arquivos tabulares dentro de uma pasta permitida.
Ter autenticado no GEE não significa ter acesso automático a todos os assets. Coleções privadas precisam ser compartilhadas com a conta que executará o MCP.
Importante: o servidor inicializa o GEE ao iniciar. Portanto, mesmo se você pretende usar somente uma etapa local pelo MCP, configure GEE_PROJECT e a autenticação Earth Engine.
Instalação passo a passo
1. Abra o PowerShell na pasta do projeto
cd C:\caminho\para\gee-mcp2. Instale as dependências
Para consultas, receitas GEE, as etapas locais que vieram de R e o desenho de mapas:
poetry install --with soildata,mapsEsse é o caminho recomendado porque instala a API Earth Engine, as bibliotecas usadas nas tabelas e modelos locais e o matplotlib usado pelos mapas nacionais.
3. Crie o arquivo de configuração
Se ainda não houver um arquivo .env:
Copy-Item .env.example .envAbra o arquivo .env e comece com uma configuração segura:
GEE_PROJECT=seu-projeto-google-cloud
SOIL_MCP_ENABLE_EXPORTS=0
SOIL_MCP_ENABLE_LOCAL_RUNS=0
# Opcional: para etapas Python locais
# SOIL_MCP_DATA_ROOT=./data
# Obrigatório para exports e para consultar/visualizar outputs próprios
# SOIL_MCP_OUTPUT_ASSET_ROOT=projects/SEU_PROJETO/assets/soil-mcpVariável | O que ela controla | Valor inicial recomendado |
GEE_PROJECT | Projeto Google Cloud usado pelo GEE | ID do seu projeto |
SOIL_MCP_ENABLE_EXPORTS | Criação de tasks/exportações GEE | 0 |
SOIL_MCP_OUTPUT_ASSET_ROOT | Raiz própria de saída no GEE | Configure antes de exportar, consultar ou abrir outputs próprios |
SOIL_MCP_ENABLE_LOCAL_RUNS | Escritas das etapas Python locais | 0 |
SOIL_MCP_DATA_ROOT | Pasta permitida para arquivos locais | ./data ou caminho absoluto |
Os flags só são habilitados pelo valor literal 1. Valores como true, yes ou True não habilitam exports nem etapas locais.
Para clientes MCP que iniciam o processo em outra pasta, prefira um caminho absoluto em SOIL_MCP_DATA_ROOT.
4. Autentique a conta Earth Engine
Use a conta que possui as permissões necessárias:
poetry run earthengine authenticate --force --auth_mode=localhost
poetry run earthengine set_project seu-projeto-google-cloudO navegador abrirá para autorizar a conta. Quando o terminal informar que o token foi salvo, a autenticação foi concluída.
O comando earthengine set_project configura o cliente de linha de comando; o servidor MCP usa especificamente o valor de GEE_PROJECT do arquivo .env.
5. Inicie o servidor MCP
poetry run python -m soil_mcpO servidor usa transporte stdio: ele não abre uma página ou painel no terminal. O cliente MCP (por exemplo, Codex) deve iniciar esse comando, usando a raiz deste repositório como diretório de trabalho.
Não é necessário abrir o Code Editor do GEE para o fluxo normal do MCP. O Code Editor pode continuar útil para inspeção ou depuração visual feita por uma pessoa técnica.
Primeiro teste seguro
Comece com perguntas que apenas leem dados:
“Quais métricas de solo publicadas estão disponíveis?”
“Qual é a média de argila de 0–10 cm nesta área?”
“Mostre as etapas do pipeline de textura.”
“Liste as receitas GEE e suas dependências.”
Essas ações usam ferramentas como list_soil_metrics, query_soil_metric, list_soil_pipeline e list_pipeline_recipes. Elas não criam tasks.
Depois, peça um plano sem executar:
“Planeje texture_training_matrix, mas não execute nada.”
“Quais inputs e outputs serão usados em carbon_prediction?”
“O que precisa existir antes de classificar textura?”
plan_pipeline_recipe monta o plano e o grafo preguiçoso do GEE, mas não inicia uma task e não grava assets.
Fluxo de uma execução real
1. Escolha um run_id
Use um nome curto e explicativo, sem espaços:
textura-teste-pr-20260729O formato aceito tem 3 a 80 caracteres e permite letras, números, hífen e sublinhado. Não use barras, espaços ou caracteres especiais.
As saídas ficam abaixo de:
<SOIL_MCP_OUTPUT_ASSET_ROOT>/runs/textura-teste-pr-20260729/...2. Planeje a receita
Exemplo conceitual de argumentos para uma predição de textura depois que a matriz de treinamento já existe:
{
"recipe_id": "texture_prediction",
"run_id": "textura-teste-pr-20260729",
"output_asset_root": "projects/SEU_PROJETO/assets/soil-mcp",
"training_asset_id": "projects/SEU_PROJETO/assets/soil-mcp/runs/textura-teste-pr-20260729/texture/texture_training_matrix"
}Peça ao MCP para chamar plan_pipeline_recipe com os argumentos. Antes de avançar, revise:
assets de entrada;
destino de cada export;
área de interesse;
escala, anos e profundidades;
se a conta consegue ler cada input;
se a saída pertence ao seu projeto.
Alguns roots padrão apontam para namespaces privados. Uma pessoa autorizada pode informar IDs reais e, quando necessário, asset_overrides no plano.
3. Habilite exports somente depois da revisão
No arquivo .env:
SOIL_MCP_ENABLE_EXPORTS=1
SOIL_MCP_OUTPUT_ASSET_ROOT=projects/SEU_PROJETO/assets/soil-mcpReinicie o servidor MCP depois de alterar o arquivo. O .env é a fonte de verdade das variáveis do servidor.
Agora faça uma solicitação explícita, por exemplo:
“Submeta o plano texture_prediction do run textura-teste-pr-20260729.”
A ferramenta submit_pipeline_recipe cria as tasks GEE. Algumas receitas podem gerar mais de uma task; revise a resposta e guarde cada task_id.
4. Acompanhe as tasks
Exemplos de pedidos:
“Liste as tarefas GEE.”
“Qual é o estado da task TASK_ID?”
“Esta task falhou? Qual foi a mensagem de erro?”
Use list_gee_tasks ou get_gee_task_status.
O MCP consulta o status quando você pergunta. Ele não permanece observando tasks sozinho nem envia alertas automáticos. Para isso, conecte um agendador ou serviço externo.
5. Veja dados e mapas sem abrir o Code Editor
Depois que uma exportação termina, o resultado continua no Earth Engine, mas pode ser consultado pelo MCP. Não é necessário baixar o raster nacional para o computador nem abrir o Code Editor.
Para ler um resultado produzido pelo pipeline, a task precisa ter concluído e o asset precisa existir abaixo de:
SOIL_MCP_OUTPUT_ASSET_ROOT/runs/<run_id>/...Também é necessário configurar SOIL_MCP_OUTPUT_ASSET_ROOT no servidor e usar uma conta que possa ler esse asset. A flag SOIL_MCP_ENABLE_EXPORTS=1 é necessária para criar novas exports, mas não para visualizar um output já existente.
Pergunta sobre um dado: o que o MCP devolve
Pedido em linguagem natural:
“Qual é a média de argila de 0–10 cm nesta área para o run textura-demo?”
O MCP identifica o run, a camada, a banda, a área e a estatística. Para um output do próprio pipeline, ele usa query_pipeline_run_asset. Para uma camada C03 catalogada que a conta possa ler, usa query_soil_metric.
Exemplo ilustrativo — números fictícios, sem consultar assets privados:
{
"run_id": "textura-demo",
"band": "argila_000_010cm",
"statistic": "mean",
"value": 42.7,
"unit": "%",
"scale_m": 30,
"source": "demonstracao_sintetica"
}Essa é uma estatística resumida da área, e não uma medição direta de campo nem uma tabela de todos os pixels. Em áreas muito grandes, o GEE pode ajustar a escala efetiva para concluir o cálculo.
Pedido de mapa: o que o MCP devolve hoje
Pedido em linguagem natural:
“Mostre o mapa de argila de 0–10 cm produzido no run textura-demo nesta área.”
O MCP usa get_pipeline_run_asset_thumbnail. Ele seleciona a banda, aplica uma visualização (mínimo, máximo e paleta) e pede ao GEE uma prévia cartográfica em PNG. A resposta contém uma URL temporária que o cliente pode exibir ou abrir.
Exemplo ilustrativo — não corresponde a uma URL real:
{
"run_id": "textura-demo",
"band": "argila_000_010cm",
"thumbnail_url": "<link temporario PNG do Earth Engine>",
"visualization": {
"min": 0,
"max": 80,
"palette": ["fff7bc", "fec44f", "d95f0e"],
"dimensions": 768
},
"source": "demonstracao_sintetica"
}Para a prévia, informe o run_id, asset_path, banda, área, mínimo, máximo, paleta e dimensão. A dimensão aceita de 128 a 2048 pixels e a paleta aceita de 2 a 12 cores. Mínimo, máximo e paleta mudam somente a aparência da imagem; não modificam os dados.
O link é temporário e não deve ser tratado como publicação permanente. A visualização também continua sujeita ao acesso da conta que pediu o mapa.
Visualizador interativo local: zoom, arrastar e camadas
Para abrir um mapa interativo real, peça ao MCP algo como:
“Abra o mapa interativo de argila e silte do run textura-demo nesta área.”
A ferramenta open_pipeline_run_asset_map valida de uma a seis camadas do mesmo run_id, cria uma sessão temporária e devolve um endereço semelhante a:
http://127.0.0.1:PORTA/viewer/SESSAO_ALEATORIAAbra esse link no navegador do mesmo computador que está rodando o MCP. O visualizador permite:
aproximar/afastar;
arrastar o mapa;
navegar pelo teclado;
escolher entre as camadas autorizadas;
ver título, banda, legenda, mínimo, máximo e paleta.
Ele não abre o Code Editor e não precisa de uma API key no navegador. Os tiles vêm de um pequeno proxy local, limitado a 127.0.0.1, que usa a autenticação Earth Engine já configurada no MCP. A sessão fica somente em memória, expira em poucos minutos e deixa de funcionar quando o MCP é encerrado.
Esse recurso não cria exports nem tasks novas. Ele requer uma task já concluída, SOIL_MCP_OUTPUT_ASSET_ROOT configurado e permissão de leitura no output.
Quando o cliente MCP pedir os parâmetros técnicos, informe a área e pelo menos uma camada. Cada camada precisa apontar para um arquivo de imagem abaixo do run, uma banda, um nome para a legenda e a escala de cores. Exemplo de uma chamada que o assistente pode montar:
{
"run_id": "textura-teste-pr-20260729",
"layers": [
{
"asset_path": "texture/prediction/argila",
"band": "argila_000_010cm",
"label": "Argila 0–10 cm",
"min_value": 0,
"max_value": 80,
"palette": ["fff7bc", "fec44f", "d95f0e"]
}
],
"bounding_box": [-48.0, -16.0, -47.8, -15.8]
}asset_path é relativo a runs/<run_id>/, não um ID livre do GEE. O visualizador só aceita caminhos, bandas e paletas literais; isso impede que um pedido de mapa escape da pasta de resultados autorizada.
Mapa nacional estático (caminho recomendado)
As camadas do MapBiomas Solo C03 já são produtos nacionais. Para ver uma delas inteira, o caminho mais rápido é gerar um PNG:
python scripts/mapa_estatico.py
python scripts/mapa_estatico.py --metric clay --depth 000_030cm
python scripts/mapa_estatico.py --metric texture_class --scale 5000Isso requer as dependências de desenho:
poetry install --with mapsO script baixa o país inteiro do GEE em uma única requisição, como uma grade de valores reais em resolução reduzida, e desenha localmente com matplotlib. Um mapa nacional sai em poucos segundos e o arquivo continua legível depois, sem sessão viva. Ele não cria export nem task.
Por que isso é muito mais rápido que o visualizador interativo: um mapa de tiles pede ao Earth Engine centenas de recortes independentes, recalculados a cada aproximação e deslocamento. A grade única troca essa conversa por um download só.
Opção | Tempo típico do Brasil inteiro | Interação | Quando usar |
scripts/mapa_estatico.py | segundos | nenhuma | Ver, comparar, salvar e compartilhar o mapa |
scripts/mapa_navegavel.py | segundos | zoom, pan, camadas, valor no cursor | Explorar o país sem esperar por tiles |
open_soil_metric_map / scripts/mapa_brasil.py | minutos | zoom, pan, camadas | Só quando precisar dos tiles do próprio GEE |
Argumentos úteis:
Argumento | Efeito |
--metric | Métrica do catálogo; repita para um painel com vários mapas |
--depth | Profundidade da métrica na mesma posição |
--scale | Resolução da grade de exibição em metros (padrão 2500; valor maior baixa menos e desenha antes) |
--bounding-box | Recorte em vez do país inteiro |
--output | Arquivo de destino (padrão mapas/brasil_<nome>.png) |
--dpi, --columns, --title | Aparência da figura |
Sem argumentos, o script desenha argila, areia e silte de 0–10 cm mais o grupamento textural de 0–30 cm. Cada métrica tem uma faixa de cores revisada: para as frações granulométricas, as faixas correspondem aos percentis 2–98 nacionais, para que a paleta cubra os valores que de fato ocorrem no Brasil. Camadas categóricas ganham cores discretas e legenda com o nome de cada classe.
A grade de exibição é uma redução de resolução só para desenho: o produto continua sendo de 30 m e as estatísticas devem vir de query_soil_metric, não da leitura visual do PNG.
Mapa navegável, sem servidor e sem sessão
Se você quer aproximar, deslocar e ler valores, mas sem a lentidão do visualizador de tiles:
python scripts/mapa_navegavel.py
python scripts/mapa_navegavel.py --metric clay --metric texture_class
python scripts/mapa_navegavel.py --scale 1500 --bounding-box -55 -25 -45 -15O script baixa a mesma grade única do mapa estático e a embute em um único arquivo HTML. Depois disso a página é autossuficiente: aproximar, deslocar, trocar de camada e ler o valor sob o cursor acontecem inteiramente no navegador. Não há requisição ao GEE, não há servidor local e não há sessão que expire — o arquivo continua funcionando amanhã.
Cada camada viaja como um PNG em tons de cinza cujo nível de cinza é a medição e cujo canal alfa carrega a máscara de validade. É por isso que a página consegue tanto colorir o raster quanto informar o valor do ponto.
O arquivo fica na ordem de alguns MB por camada. Use --scale para equilibrar detalhe e tamanho: 2000 m para o país inteiro, valores menores para um recorte.
O valor mostrado é o da grade de exibição, não o do pixel de 30 m. Para número com precisão de produto, use query_soil_metric.
Mapa nacional interativo por tiles
Se você precisa aproximar e navegar, peça algo como:
“Abra o mapa de argila e areia do Brasil.”
A ferramenta open_soil_metric_map usa o visualizador local, com duas diferenças em relação a open_pipeline_run_asset_map:
os assets vêm do catálogo fixo de list_soil_metrics, e não de um run_id próprio — portanto ela não exige SOIL_MCP_OUTPUT_ASSET_ROOT nem uma execução concluída;
a área padrão é o Brasil inteiro, e cada camada é recortada no limite nacional (USDOS/LSIB_SIMPLE/2017, um dataset público do GEE), de modo que apenas o país aparece desenhado.
Fora de um cliente MCP:
python scripts/mapa_brasil.py --minutes 60O script imprime o endereço do visualizador, abre o navegador e mantém a sessão viva até você encerrar com Ctrl+C.
Em escala nacional esse caminho é lento: cada tile é recalculado pelo GEE sob demanda e a sessão não guarda cache entre deslocamentos. Para olhar o país inteiro, prefira o mapa estático; reserve o visualizador para aproximar uma área.
Prévia estática versus visualizador interativo
Formato | Situação atual | Para que serve |
Mapa nacional em PNG | Disponível por scripts/mapa_estatico.py para as camadas C03 publicadas | Ver o país inteiro em segundos, com barra de cores e legenda, e guardar o arquivo |
Mapa navegável em HTML | Disponível por scripts/mapa_navegavel.py para as camadas C03 publicadas | Aproximar, deslocar e ler valores sem servidor, sem sessão e sem consultar o GEE |
Prévia cartográfica PNG | Disponível para assets concluídos do próprio run_id | Ver rapidamente cores, padrões espaciais e uma área específica, sem abrir o Code Editor |
Visualizador local com zoom/pan/camadas | Disponível por open_pipeline_run_asset_map (run próprio) e open_soil_metric_map (camadas C03 publicadas) | Aproximar uma área no navegador local, sem expor credenciais Google |
O arquivo arquitetura-gee-mcp.html mostra o contrato real da entrega: pergunta → resultado estruturado → viewer_url do mapa local. Ele não desenha um mapa fictício; as tiles verdadeiras só aparecem quando uma sessão autorizada é criada pelo MCP.
Hoje, o MCP não gera thumbnail PNG para as camadas C03 catalogadas: para elas existem métricas numéricas e o mapa interativo nacional. O thumbnail é destinado a outputs versionados do seu próprio pipeline, por segurança.
Etapas locais: portabilidade de R para Python
Várias etapas que eram executadas em R foram reorganizadas para Python local. Isso evita rodar scripts arbitrários e permite que o MCP conheça as entradas, saídas e dependências de cada etapa.
Habilite o fluxo local quando precisar
No .env:
SOIL_MCP_DATA_ROOT=./data
SOIL_MCP_ENABLE_LOCAL_RUNS=1Todos os arquivos usados pelo MCP precisam ficar dentro de SOIL_MCP_DATA_ROOT. Essa limitação protege o restante do computador.
Fluxo recomendado
Use list_soildata_pipeline para ver as etapas e seus estados.
Use get_soildata_stage para entender entradas, saídas e dependências.
Use plan_soildata_stage para conferir caminhos e opções sem criar uma saída.
Use run_soildata_stage somente depois da revisão.
Exemplo conceitual:
{
"stage_id": "export_psd_modeling_data",
"input_paths": {
"input": "15_soildata.parquet"
},
"output_path": "16_psd_modeling.parquet"
}O planejamento local aceita caminhos de entrada ainda inexistentes para permitir organizar o fluxo. A execução verifica se os inputs existem. O MCP não roda R, Python ou comandos arbitrários; ele executa somente estágios previamente permitidos.
Permissões necessárias
Capacidade | Por que é necessária | Exemplo de falha |
Usar Earth Engine no projeto GCP | Enviar consultas e tasks | Projeto não configurado ou conta não habilitada |
Ler assets privados | Usar amostras, matrizes e covariáveis | Permission denied ao acessar um asset |
Escrever na saída própria | Salvar resultados de um run | Raiz ausente ou sem permissão |
Ler/escrever tabelas locais | Rodar Python local | Arquivo fora de SOIL_MCP_DATA_ROOT |
Para exportações, duas regras são obrigatórias:
SOIL_MCP_ENABLE_EXPORTS precisa valer 1.
O destino precisa ser a raiz configurada em SOIL_MCP_OUTPUT_ASSET_ROOT ou uma subpasta dela.
A raiz de saída deve pertencer ao operador ou permitir a criação de filhos. As receitas não sobrescrevem assets existentes; para um novo teste, use outro run_id.
Ferramentas MCP por objetivo
Objetivo | Ferramentas | Exemplo de pedido |
Ver métricas publicadas | list_soil_metrics | “Quais produtos posso consultar?” |
Calcular uma métrica | query_soil_metric | “Qual é a média de argila nesta área?” |
Gerar o mapa nacional em PNG | scripts/mapa_estatico.py | “Gere o mapa de argila do Brasil.” |
Navegar pelo mapa nacional | scripts/mapa_navegavel.py | “Quero aproximar e ver os valores.” |
Abrir o mapa por tiles do GEE | open_soil_metric_map | “Abra o mapa com tiles do Earth Engine.” |
Exportar uma camada publicada | submit_soil_layer_export | “Exporte esta camada para minha pasta autorizada.” |
Entender o fluxo de referência | list_soil_pipeline, get_soil_pipeline_stage, read_soil_pipeline_source | “Como esta etapa depende da anterior?” |
Listar receitas GEE | list_pipeline_recipes | “Quais receitas existem para carbono?” |
Planejar sem escrever | plan_pipeline_recipe | “Planeje, mas não execute.” |
Submeter receita | submit_pipeline_recipe | “Agora pode enviar as tasks.” |
Monitorar tasks | list_gee_tasks, get_gee_task_status | “A tarefa terminou?” |
Consultar output próprio | query_pipeline_run_asset | “Qual a média da camada produzida?” |
Gerar prévia de mapa de um run próprio | get_pipeline_run_asset_thumbnail | “Mostre um mapa deste resultado.” |
Abrir mapa interativo de um run próprio | open_pipeline_run_asset_map | “Abra o mapa interativo desta camada nesta área.” |
Trabalhar com tabela local | list_soildata_pipeline, get_soildata_stage, plan_soildata_stage, run_soildata_stage | “Planeje a limpeza desta tabela.” |
O que validar antes de rodar uma área grande
A arquitetura permite executar grande parte da cadeia, mas reproduzir um produto científico exige mais do que código:
mesmos dados autorizados;
versões corretas de covariáveis e tabelas;
nomes de colunas, bandas, unidades e schemas esperados;
pseudoamostras, limites e correções manuais quando o fluxo original as usa;
comparação com uma linha de base autorizada;
aprovação do responsável científico antes de publicar.
Modelos/bibliotecas diferentes não garantem resultados idênticos pixel a pixel. Em especial, comportamentos de ranger, gbm, qmap e implementações Python/GEE podem variar.
Caminho seguro:
acesso autorizado
→ consulta de leitura
→ plano da receita
→ teste em área pequena
→ comparação com referência
→ validação de mapa e métricas
→ processamento maiorLimitações conhecidas
Alguns inputs privados não estão no repositório: SoilData-ctb, pseudoamostras, matrizes PSD/SOC, shapefiles auxiliares e certos assets MapBiomas.
Algumas portas de R para Python são aproximações e precisam ser verificadas com dados reais.
Rotinas antigas que dependiam de Google Drive/Insync não são a infraestrutura operacional deste projeto; se forem necessárias, precisam de destino institucional definido.
O MCP não envia alertas de task em segundo plano.
Planejar pode funcionar sem permissão total porque apenas monta referências; executar ou consultar falhará se a conta não puder ler o asset.
O MCP não toma decisões científicas nem substitui revisão humana.
Solução de problemas
“Este app está bloqueado” durante a autenticação
Tente novamente no modo local:
poetry run earthengine authenticate --force --auth_mode=localhostEscolha a conta habilitada para Earth Engine. Se o terminal confirmar que o token foi salvo, a autenticação terminou. Se o bloqueio persistir, verifique o registro da conta/projeto no Earth Engine e políticas institucionais de login.
“Permission denied” ao acessar um asset
Autenticação não é permissão de leitura. Peça ao responsável que compartilhe a coleção, tabela ou imagem exata com a conta usada pelo MCP.
“Exports are disabled”
Isso é intencional. Revise o plano e configure:
SOIL_MCP_ENABLE_EXPORTS=1
SOIL_MCP_OUTPUT_ASSET_ROOT=projects/SEU_PROJETO/assets/soil-mcpReinicie o MCP depois da alteração.
Erro de raiz de saída
O destino informado deve ser a raiz configurada em SOIL_MCP_OUTPUT_ASSET_ROOT ou uma subpasta dela. Isso evita exports para coleções não autorizadas.
Arquivo local não encontrado ou caminho proibido
Coloque o arquivo dentro de SOIL_MCP_DATA_ROOT e informe um caminho relativo, por exemplo entrada/15_soildata.parquet. O MCP bloqueia caminhos que tentem sair dessa pasta.
A task falhou
Consulte o task_id. Verifique primeiro asset de entrada, permissões, nome de banda/coluna, escala, área e destino de saída. Corrija e teste em uma área pequena.
Estrutura do repositório
src/soil_mcp/
├── recipes/ # receitas Python para Google Earth Engine
├── soildata/ # substituições Python dos scripts R/notebooks
├── *_tools.py # ferramentas expostas ao cliente MCP
└── pipeline.py # ordem e contratos das etapas
scripts/ # entradas de terminal, como o mapa nacional
soil_30m_landsat/ # fonte original preservada para comparação
tests/ # testes de contrato e transformações
README.md # este manual operacional
arquitetura-gee-mcp.html # guia visual e didático
mapa-interativo.html # template do visualizador por tiles do GEE
mapa-navegavel.html # template do mapa navegável autossuficienteDesenvolvimento e validação
Para executar os testes:
poetry run pytest -qOs testes verificam contratos do pipeline e transformações locais. Eles não substituem a validação científica com os assets privados reais.
Próximos passos recomendados
Confirme a conta, o projeto GCP e as permissões de leitura.
Faça uma consulta simples a um produto publicado.
Peça o plano de uma receita, sem executar.
Conecte IDs reais de tabelas, pontos e assets privados autorizados.
Rode um teste pequeno.
Compare métricas e mapa contra uma referência.
Só então habilite uma exportação maior.
Atribuição e uso de dados
Os termos de uso, regras de atribuição e políticas de acesso da MapBiomas e das demais fontes continuam valendo. Este projeto organiza execução e rastreabilidade; ele não transfere propriedade, licença ou permissões sobre os dados.
This server cannot be installed
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Servers
- -license-quality-maintenanceEnables satellite imagery analysis through Google Earth Engine, allowing users to search datasets, calculate vegetation indices like NDVI, filter collections by location and date, and export imagery to cloud storage. Supports major satellite datasets including Sentinel-2, Landsat, and MODIS for applications like agriculture monitoring and deforestation tracking.Last updated
- Alicense-qualityDmaintenanceProduction-ready satellite imagery analysis server that enables natural language queries for Earth observation data, including land cover classification, vegetation monitoring, water detection, change detection, and automated environmental reporting.Last updatedMIT
- AlicenseBqualityDmaintenanceProvides tools to search, download, and manage satellite imagery from all Copernicus Sentinel missions via the Copernicus Data Space ecosystem. It enables advanced geospatial queries, temporal coverage analysis, and automated data management for Earth observation tasks.Last updated133LGPL 3.0
- Alicense-qualityDmaintenanceMCP server for interacting with Google Earth Engine, enabling geospatial analysis such as dataset visualization, statistics computation, and search via AI assistants.Last updated13MIT
Related MCP Connectors
OpenTopography global DEM rasters + point queries (free key)
Search and query government open-data portals (Socrata SODA API).
Query real-time and historical USGS water data from ~8,000 stream gages and groundwater wells.
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/VitorEduardoLimaKenor/soil-pipeline-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server