Node Mantis
oficialAutomaçã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_datapara 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_taskecancel_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:
- Copie uma chave de API do painel.
- Adicione a entrada abaixo ao seu assistente. O local depende do assistente; consulte a tabela e as seções a seguir.
- 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.commandeargsdefinem como o assistente inicia o servidor. Use a versão para Node.js ou para Python; ambas fornecem as mesmas ferramentas ao assistente.envconté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 comnodemantis configure, pode omitirenv.
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.
| Assistente | Onde adicionar a entrada |
|---|---|
| Claude Code | Um comando no terminal. |
| Claude Desktop | claude_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. |
| Codex | Um 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
| Ferramenta | Descrição |
|---|---|
run_task | Executa uma tarefa em um site a partir de um objetivo em linguagem simples: navega, clica, digita, preenche formulários e lê o resultado. |
retrieve_data | Abre uma página e lê dados dela sem fazer alterações. |
get_task | Aguarda uma tarefa e retorna seu status, o progresso mais recente e o resultado. |
cancel_task | Interrompe 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âmetro | Tipo | Padrão | Descrição |
|---|---|---|---|
goal | string | obrigatório | O que realizar, em linguagem simples, com todos os detalhes necessários para concluir a tarefa. |
start_url | string | nenhum | Página a abrir primeiro. Sem ela, a tarefa encontra seu próprio caminho a partir do objetivo. |
result_schema | object | formato livre | JSON Schema dos dados a retornar. O resultado então contém os dados nesse formato. |
effort | low | medium | high | xhigh | médio | Quanto da capacidade utilizar. Um esforço maior pode lidar com páginas mais difíceis e custa mais. |
max_cost_usd | number | sem limite | Orçamento em USD verificado entre etapas. A etapa final pode elevar o gasto total acima desse valor. |
max_steps | integer | 30 | Número máximo de etapas antes de a tarefa ser interrompida. |
timeout_seconds | integer | 300 | Limite de tempo total da tarefa. |
secrets | string[] | nenhum | Nomes dos valores privados que a tarefa pode digitar. Cada valor é lido de NODEMANTIS_SECRET_<NAME> no ambiente do servidor. |
use_proxy | boolean | false | Direciona o navegador pelo proxy configurado no ambiente do servidor. |
show_browser | boolean | false | Exibe 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âmetro | Tipo | Padrão | Descrição |
|---|---|---|---|
url | string | obrigatório | A página a ser lida. |
prompt | string | obrigatório | O que ler na página. |
result_schema | object | formato livre | JSON Schema do formato dos dados retornados. |
effort | low | medium | high | xhigh | médio | Quanto da capacidade utilizar para ler a página. |
use_proxy | boolean | false | Direciona o navegador pelo proxy configurado no ambiente do servidor. |
show_browser | boolean | false | Exibe a janela do navegador enquanto a página é lida. |
get_task
| Parâmetro | Tipo | Padrão | Descrição |
|---|---|---|---|
task_id | string | obrigatório | O task_id retornado por run_task ou retrieve_data. |
wait_seconds | integer | 45 | Quanto 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âmetro | Tipo | Padrão | Descrição |
|---|---|---|---|
--wait-seconds <n> | number | 45 | Quanto 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> | number | 4 | Quantas tarefas podem ser executadas ao mesmo tempo. |
-H, --headed | flag | headless | Exibe 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_KEYaenvdo servidor ou executenodemantis configureuma vez e tente novamente. Não é necessário reiniciar apósconfigure. - O servidor atinge o tempo limite na primeira inicialização. A primeira inicialização de
npxbaixa o pacote. Instale-o uma vez comnpm install -g node-mantise inicie o comando instalado:{ "mcpServers": { "node-mantis": { "command": "nodemantis", "args": ["mcp"] } } } - As tarefas não iniciam. Execute
nodemantis doctorpara verificar a instalação, o navegador e a chave de API.