Node Mantis

oficial

Automação web: descreva uma tarefa em um site em inglês simples, e o Node Mantis interage com a página em um navegador real e retorna dados estruturados.

O que você pode fazer com Node Mantis MCP?

  • Executar tarefas em sites — Informe um objetivo em linguagem simples, e o Node Mantis clica, digita e preenche formulários em um navegador real.
  • Retornar dados estruturados — Forneça um JSON Schema e receba o resultado da tarefa como dados que correspondem a essa estrutura.
  • Ler uma única página — Use retrieve_data para extrair informações específicas de uma URL sem alterar nada.
  • Gerenciar tarefas de longa duração — Verifique o progresso ou interrompa uma tarefa em segundo plano com get_task e cancel_task.
  • Manter segredos fora do chat — Faça referência a valores armazenados como <secret:NAME> para que senhas e códigos nunca passem pela conversa.

Documentação

Servidor MCP

O Node Mantis inclui um servidor Model Context Protocol (MCP). Adicione-o a um assistente de IA compatível com MCP, como Claude Code, Claude Desktop, Cursor, VS Code ou Codex, e o assistente poderá executar tarefas em sites para você: ele descreve a tarefa, o Node Mantis navega pelo site em um navegador real e retorna o resultado como dados estruturados.

Adicionar o servidor ao seu agente de programação ou assistente permite:

  • Executar tarefas em sites. Informe um objetivo em linguagem simples e o Node Mantis navega pelo site como um usuário real faria: clicando, digitando e preenchendo formulários, menus suspensos e seletores de data.
  • Obter resultados estruturados. Forneça um JSON Schema e o Node Mantis retorna o resultado como dados que correspondem a ele.
  • Executar tarefas longas em segundo plano. Uma tarefa que leva minutos continua em execução enquanto o assistente verifica seu andamento, informa o progresso ou a cancela.

O servidor faz parte do pacote node-mantis no npm e no PyPI, então não há nada separado para instalar. Seu assistente o inicia com um comando, usando Node.js:

npx -y node-mantis mcp

ou usando Python com uv:

uvx node-mantis mcp

Ambas as opções fornecem as mesmas ferramentas ao assistente. Você precisa do Node.js ou Python, do Google Chrome e de uma chave de API do painel. Se o Chrome não estiver instalado, a primeira tarefa baixa o Chrome for Testing.

Adicionar ao seu assistente

Cada assistente mantém uma lista de servidores MCP nas configurações. Você adiciona uma entrada para o Node Mantis, usando um comando ou editando o arquivo de configurações do assistente, e o próprio assistente inicia o servidor sempre que precisar dele. São três etapas:

  1. Copie uma chave de API do painel.
  2. Adicione a entrada abaixo ao seu assistente. O local depende do assistente; consulte a tabela e as seções a seguir.
  3. Reinicie o assistente e verifique se está funcionando.

A maioria dos assistentes lê a mesma entrada JSON. Com Node.js:

{
  "mcpServers": {
    "node-mantis": {
      "command": "npx",
      "args": ["-y", "node-mantis", "mcp"],
      "env": { "NODEMANTIS_API_KEY": "sk_live_<copy-from-dashboard>" }
    }
  }
}

Com Python:

{
  "mcpServers": {
    "node-mantis": {
      "command": "uvx",
      "args": ["node-mantis", "mcp"],
      "env": { "NODEMANTIS_API_KEY": "sk_live_<copy-from-dashboard>" }
    }
  }
}

A entrada tem três partes:

  • node-mantis é o nome que o assistente exibe para o servidor. Você pode alterá-lo.
  • command e args definem como o assistente inicia o servidor. Use a versão para Node.js ou para Python; ambas fornecem as mesmas ferramentas ao assistente.
  • env contém as configurações que o assistente passa ao servidor ao iniciá-lo. Substitua o marcador pela sua chave de API. Se você já salvou uma chave com nodemantis configure, pode omitir env.

Se o arquivo de configurações já tiver uma seção mcpServers, adicione a entrada node-mantis dentro dela, junto às demais, em vez de colar um segundo mcpServers.

AssistenteOnde adicionar a entrada
Claude CodeUm comando no terminal.
Claude Desktopclaude_desktop_config.json, aberto em Settings.
Cursor~/.cursor/mcp.json para todos os projetos ou .cursor/mcp.json em um projeto.
VS Code.vscode/mcp.json no seu workspace.
CodexUm comando no terminal ou ~/.codex/config.toml.

Claude Code

Execute um destes comandos no terminal. Com Node.js:

claude mcp add node-mantis -e NODEMANTIS_API_KEY="sk_live_<copy-from-dashboard>" -- npx -y node-mantis mcp

Com Python:

claude mcp add node-mantis -e NODEMANTIS_API_KEY="sk_live_<copy-from-dashboard>" -- uvx node-mantis mcp

claude mcp list então mostra node-mantis como conectado.

Claude Desktop

Abra Settings, depois Developer e, em seguida, Edit Config. Isso abre claude_desktop_config.json, armazenado em ~/Library/Application Support/Claude/ no macOS e em %APPDATA%\Claude\ no Windows. Adicione a entrada JSON acima, salve o arquivo e reinicie o aplicativo.

Cursor

Adicione a entrada JSON acima a ~/.cursor/mcp.json para usá-la em todos os projetos ou a .cursor/mcp.json dentro de um projeto. Crie o arquivo se ele não existir.

VS Code

O VS Code usa servers em vez de mcpServers. Adicione isto a .vscode/mcp.json no seu workspace:

{
  "servers": {
    "node-mantis": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "node-mantis", "mcp"],
      "env": { "NODEMANTIS_API_KEY": "sk_live_<copy-from-dashboard>" }
    }
  }
}

Para Python, defina command como uvx e args como ["node-mantis", "mcp"].

Codex

Execute um destes comandos no terminal. Com Node.js:

codex mcp add node-mantis --env NODEMANTIS_API_KEY="sk_live_<copy-from-dashboard>" -- npx -y node-mantis mcp

Com Python:

codex mcp add node-mantis --env NODEMANTIS_API_KEY="sk_live_<copy-from-dashboard>" -- uvx node-mantis mcp

Ou edite ~/.codex/config.toml. O limite de inicialização mais longo dá tempo para que o pacote seja baixado na primeira execução:

[mcp_servers.node-mantis]
command = "npx"
args = ["-y", "node-mantis", "mcp"]
startup_timeout_sec = 60

[mcp_servers.node-mantis.env]
NODEMANTIS_API_KEY = "sk_live_<copy-from-dashboard>"

Para Python, defina command como "uvx" e args como ["node-mantis", "mcp"].

Python sem uv

Os exemplos de Python acima usam uv, que busca o pacote no PyPI na primeira utilização. Sem uv, instale o pacote uma vez com python -m pip install node-mantis e use nodemantis como comando, com mcp como único argumento:

{
  "mcpServers": {
    "node-mantis": {
      "command": "nodemantis",
      "args": ["mcp"],
      "env": { "NODEMANTIS_API_KEY": "sk_live_<copy-from-dashboard>" }
    }
  }
}

Verificar se está funcionando

Após reiniciar, o assistente lista node-mantis entre os servidores MCP, com quatro ferramentas. Em seguida, peça uma tarefa, por exemplo:

Use Node Mantis to open https://sandbox.nodemantis.com and tell me the title and price of the first book.

O assistente chama run_task e responde com o que a tarefa encontrou. Se isso não acontecer, consulte Solução de problemas.

Windows

Se o assistente não conseguir iniciar npx diretamente, execute-o por meio de cmd:

{
  "mcpServers": {
    "node-mantis": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "node-mantis", "mcp"],
      "env": { "NODEMANTIS_API_KEY": "sk_live_<copy-from-dashboard>" }
    }
  }
}

Ferramentas

FerramentaDescrição
run_taskExecuta uma tarefa em um site a partir de um objetivo em linguagem simples: navega, clica, digita, preenche formulários e lê o resultado.
retrieve_dataAbre uma página e lê dados dela sem fazer alterações.
get_taskAguarda uma tarefa e retorna seu status, o progresso mais recente e o resultado.
cancel_taskInterrompe uma tarefa em execução e fecha o navegador.

Cada tarefa é executada em uma sessão nova e independente do navegador, sem logins salvos, e a sessão é encerrada quando a tarefa termina.

run_task

Funciona como run no SDK. Somente goal é obrigatório.

ParâmetroTipoPadrãoDescrição
goalstringobrigatórioO que realizar, em linguagem simples, com todos os detalhes necessários para concluir a tarefa.
start_urlstringnenhumPágina a abrir primeiro. Sem ela, a tarefa encontra seu próprio caminho a partir do objetivo.
result_schemaobjectformato livreJSON Schema dos dados a retornar. O resultado então contém os dados nesse formato.
effortlow | medium | high | xhighmédioQuanto da capacidade utilizar. Um esforço maior pode lidar com páginas mais difíceis e custa mais.
max_cost_usdnumbersem limiteOrçamento em USD verificado entre etapas. A etapa final pode elevar o gasto total acima desse valor.
max_stepsinteger30Número máximo de etapas antes de a tarefa ser interrompida.
timeout_secondsinteger300Limite de tempo total da tarefa.
secretsstring[]nenhumNomes dos valores privados que a tarefa pode digitar. Cada valor é lido de NODEMANTIS_SECRET_<NAME> no ambiente do servidor.
use_proxybooleanfalseDireciona o navegador pelo proxy configurado no ambiente do servidor.
show_browserbooleanfalseExibe a janela do navegador enquanto a tarefa é executada.

retrieve_data

Funciona como retrieve no SDK. Use run_task em vez disso quando chegar aos dados exigir cliques, digitação ou várias páginas.

ParâmetroTipoPadrãoDescrição
urlstringobrigatórioA página a ser lida.
promptstringobrigatórioO que ler na página.
result_schemaobjectformato livreJSON Schema do formato dos dados retornados.
effortlow | medium | high | xhighmédioQuanto da capacidade utilizar para ler a página.
use_proxybooleanfalseDireciona o navegador pelo proxy configurado no ambiente do servidor.
show_browserbooleanfalseExibe a janela do navegador enquanto a página é lida.

get_task

ParâmetroTipoPadrãoDescrição
task_idstringobrigatórioO task_id retornado por run_task ou retrieve_data.
wait_secondsinteger45Quanto tempo aguardar a conclusão da tarefa antes de responder. 0 responde imediatamente.

cancel_task

Recebe um task_id. Uma tarefa que já terminou permanece inalterada.

Tarefas longas

Uma tarefa em um site pode levar mais tempo do que o assistente está disposto a esperar por uma chamada de ferramenta. Por isso, run_task e retrieve_data aguardam até 45 segundos. Se a tarefa terminar nesse período, a chamada retorna o resultado. Caso contrário, retorna o status running com um task_id, e a tarefa continua em execução em segundo plano:

{
  "task_id": "task_6f0c2a54-8f0e-4f0a-9d2b-2f6c1f1f8a10",
  "tool": "run_task",
  "status": "running",
  "elapsed_seconds": 45,
  "progress": {
    "step": 6,
    "max_steps": 30,
    "message": "Step 6/30: The cart shows one book. — click(\"Checkout\")"
  },
  "next_step": "Still running. Call get_task with task_id \"task_6f0c2a54-8f0e-4f0a-9d2b-2f6c1f1f8a10\" to wait for the result, or cancel_task to stop it."
}

Em seguida, o assistente chama get_task com esse id até que o status seja succeeded, failed ou cancelled:

{
  "task_id": "task_6f0c2a54-8f0e-4f0a-9d2b-2f6c1f1f8a10",
  "tool": "run_task",
  "status": "succeeded",
  "elapsed_seconds": 71,
  "result": {
    "ok": true,
    "reason": "Added the book to the cart and read the cart.",
    "value": { "title": "Journey to the Center of the Earth", "quantity": 1 },
    "steps": 9,
    "cost_usd": 0.04,
    "trace_id": "op_1794979105280_5c3e8996"
  }
}

Uma tarefa failed ainda retorna o que encontrou, junto com o motivo, para que o assistente possa ajustar o objetivo e tentar novamente. As tarefas concluídas são mantidas por uma hora. As tarefas pertencem ao servidor em execução: elas param quando o assistente fecha o servidor.

Segredos

Senhas e códigos de uso único nunca passam pela conversa. Defina cada valor no ambiente do servidor como NODEMANTIS_SECRET_<NAME>, junto à chave de API em env. O assistente passa apenas os nomes em secrets e faz referência a um valor no objetivo como <secret:NAME>. Consulte Segredos.

Proxy

Para direcionar o navegador de uma tarefa por um proxy, defina NODEMANTIS_PROXY no ambiente do servidor e faça a tarefa passar use_proxy. Listas e arquivos de proxy funcionam conforme descrito em Configuração de proxy.

Opções do servidor

Adicione estas opções após mcp na lista args.

ParâmetroTipoPadrãoDescrição
--wait-seconds <n>number45Quanto tempo uma chamada de ferramenta aguarda uma tarefa antes de retornar o id da tarefa. Reduza esse valor se o assistente desistir das chamadas de ferramenta mais cedo.
--max-tasks <n>number4Quantas tarefas podem ser executadas ao mesmo tempo.
-H, --headedflagheadlessExibe a janela do navegador para cada tarefa, a menos que uma chamada de ferramenta defina show_browser.

Solução de problemas

  • O assistente informa que nenhuma chave de API está configurada. Adicione NODEMANTIS_API_KEY a env do servidor ou execute nodemantis configure uma vez e tente novamente. Não é necessário reiniciar após configure.
  • O servidor atinge o tempo limite na primeira inicialização. A primeira inicialização de npx baixa o pacote. Instale-o uma vez com npm install -g node-mantis e inicie o comando instalado:
    {
      "mcpServers": {
        "node-mantis": {
          "command": "nodemantis",
          "args": ["mcp"]
        }
      }
    }
    
  • As tarefas não iniciam. Execute nodemantis doctor para verificar a instalação, o navegador e a chave de API.