Node Mantis
oficialAutomatización web: describe una tarea en un sitio web en inglés sencillo; Node Mantis interactúa con la página web en un navegador real y devuelve datos estructurados.
¿Qué puedes hacer con Node Mantis MCP?
- Ejecutar tareas en sitios web — Indica un objetivo en lenguaje sencillo y Node Mantis hace clic, escribe y completa formularios en un navegador real.
- Devolver datos estructurados — Proporciona un esquema JSON y recibe el resultado de la tarea como datos que se ajustan a esa estructura.
- Leer una sola página — Usa
retrieve_datapara extraer información específica de una URL sin cambiar nada. - Gestionar tareas de larga duración — Consulta el progreso o detén una tarea en segundo plano con
get_taskycancel_task. - Mantener los secretos fuera del chat — Haz referencia a los valores almacenados como
<secret:NAME>para que las contraseñas y los códigos nunca pasen por la conversación.
Documentación
Servidor MCP
Node Mantis incluye un servidor Model Context Protocol (MCP). Añádelo a un asistente de IA compatible con MCP, como Claude Code, Claude Desktop, Cursor, VS Code o Codex, y el asistente podrá realizar tareas en sitios web por ti: describe la tarea, Node Mantis navega por el sitio en un navegador real y devuelve el resultado como datos estructurados.
Al añadir el servidor a tu agente de programación o asistente, podrás:
- Realizar tareas en sitios web. Indica un objetivo en español sencillo y Node Mantis navegará por el sitio como lo haría un usuario real: hará clic, escribirá y gestionará formularios, menús desplegables y selectores de fecha.
- Obtener resultados estructurados. Proporciona un JSON Schema y Node Mantis devolverá el resultado como datos que se ajustan a él.
- Ejecutar tareas largas en segundo plano. Una tarea que tarda varios minutos sigue ejecutándose mientras el asistente consulta su estado, informa del progreso o la cancela.
El servidor forma parte del paquete node-mantis en npm y PyPI, así que no hay que instalar nada por separado. El asistente lo inicia con un solo comando, mediante Node.js:
npx -y node-mantis mcp
o mediante Python con uv:
uvx node-mantis mcp
Ambas opciones proporcionan al asistente las mismas herramientas. Necesitas Node.js o Python, Google Chrome y una clave de API del panel. Si Chrome no está instalado, la primera tarea descarga Chrome for Testing.
Añadirlo a tu asistente
Cada asistente mantiene una lista de servidores MCP en su configuración. Añade una entrada para Node Mantis, ya sea con un comando o editando el archivo de configuración del asistente, y el propio asistente iniciará el servidor cuando lo necesite. Hay tres pasos:
- Copia una clave de API del panel.
- Añade la entrada siguiente a tu asistente. La ubicación depende del asistente; consulta la tabla y las secciones siguientes.
- Reinicia el asistente y comprueba que funciona.
La mayoría de los asistentes leen la misma entrada JSON. Con Node.js:
{
"mcpServers": {
"node-mantis": {
"command": "npx",
"args": ["-y", "node-mantis", "mcp"],
"env": { "NODEMANTIS_API_KEY": "sk_live_<copy-from-dashboard>" }
}
}
}
Con Python:
{
"mcpServers": {
"node-mantis": {
"command": "uvx",
"args": ["node-mantis", "mcp"],
"env": { "NODEMANTIS_API_KEY": "sk_live_<copy-from-dashboard>" }
}
}
}
La entrada tiene tres partes:
node-mantises el nombre que el asistente muestra para el servidor. Puedes cambiarlo.commandyargsindican cómo inicia el asistente el servidor. Usa la versión de Node.js o la de Python; ambas proporcionan al asistente las mismas herramientas.envcontiene la configuración que el asistente pasa al servidor al iniciarlo. Sustituye el marcador de posición por tu clave de API. Si ya guardaste una clave connodemantis configure, puedes omitirenv.
Si el archivo de configuración ya tiene una sección mcpServers, añade la entrada node-mantis dentro de ella, junto a las demás, en lugar de pegar un segundo mcpServers.
| Asistente | Dónde va la entrada |
|---|---|
| Claude Code | Un comando en tu terminal. |
| Claude Desktop | claude_desktop_config.json, que se abre desde Settings. |
| Cursor | ~/.cursor/mcp.json para todos los proyectos, o .cursor/mcp.json en un solo proyecto. |
| VS Code | .vscode/mcp.json en tu espacio de trabajo. |
| Codex | Un comando en tu terminal, o ~/.codex/config.toml. |
Claude Code
Ejecuta uno de estos comandos en tu terminal. Con Node.js:
claude mcp add node-mantis -e NODEMANTIS_API_KEY="sk_live_<copy-from-dashboard>" -- npx -y node-mantis mcp
Con Python:
claude mcp add node-mantis -e NODEMANTIS_API_KEY="sk_live_<copy-from-dashboard>" -- uvx node-mantis mcp
A continuación, claude mcp list muestra node-mantis como conectado.
Claude Desktop
Abre Settings, luego Developer y, después, Edit Config. Se abrirá claude_desktop_config.json, que se encuentra en ~/Library/Application Support/Claude/ en macOS y en %APPDATA%\Claude\ en Windows. Añade la entrada JSON anterior, guarda el archivo y reinicia la aplicación.
Cursor
Añade la entrada JSON anterior a ~/.cursor/mcp.json para usarla en todos los proyectos, o a .cursor/mcp.json dentro de un solo proyecto. Crea el archivo si no existe.
VS Code
VS Code usa servers en lugar de mcpServers. Añade esto a .vscode/mcp.json en tu espacio de trabajo:
{
"servers": {
"node-mantis": {
"type": "stdio",
"command": "npx",
"args": ["-y", "node-mantis", "mcp"],
"env": { "NODEMANTIS_API_KEY": "sk_live_<copy-from-dashboard>" }
}
}
}
Para Python, establece command en uvx y args en ["node-mantis", "mcp"].
Codex
Ejecuta uno de estos comandos en tu terminal. Con Node.js:
codex mcp add node-mantis --env NODEMANTIS_API_KEY="sk_live_<copy-from-dashboard>" -- npx -y node-mantis mcp
Con Python:
codex mcp add node-mantis --env NODEMANTIS_API_KEY="sk_live_<copy-from-dashboard>" -- uvx node-mantis mcp
O edita ~/.codex/config.toml. El límite de inicio más largo da tiempo a la primera ejecución para descargar el paquete:
[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, establece command en "uvx" y args en ["node-mantis", "mcp"].
Python sin uv
Los ejemplos de Python anteriores usan uv, que obtiene el paquete de PyPI la primera vez que se usa. Si no tienes uv, instala el paquete una vez con python -m pip install node-mantis y usa nodemantis como comando, con mcp como único argumento:
{
"mcpServers": {
"node-mantis": {
"command": "nodemantis",
"args": ["mcp"],
"env": { "NODEMANTIS_API_KEY": "sk_live_<copy-from-dashboard>" }
}
}
}
Comprobar que funciona
Después de reiniciar, el asistente muestra node-mantis entre sus servidores MCP, con cuatro herramientas. A continuación, pídele que realice una tarea, por ejemplo:
Use Node Mantis to open https://sandbox.nodemantis.com and tell me the title and price of the first book.
El asistente llama a run_task y responde con lo que encontró la tarea. Si no lo hace, consulta Solución de problemas.
Windows
Si el asistente no puede iniciar npx directamente, ejecútalo mediante cmd:
{
"mcpServers": {
"node-mantis": {
"command": "cmd",
"args": ["/c", "npx", "-y", "node-mantis", "mcp"],
"env": { "NODEMANTIS_API_KEY": "sk_live_<copy-from-dashboard>" }
}
}
}
Herramientas
| Herramienta | Descripción |
|---|---|
run_task | Realiza una tarea en un sitio web a partir de un objetivo expresado en español sencillo: navega, hace clic, escribe, rellena formularios y lee el resultado. |
retrieve_data | Abre una página y lee datos de ella sin modificar nada. |
get_task | Espera a que termine una tarea y devuelve su estado, el progreso más reciente y el resultado. |
cancel_task | Detiene una tarea en curso y cierra su navegador. |
Cada tarea se ejecuta en una sesión nueva e independiente del navegador, sin inicios de sesión guardados, y la sesión se cierra cuando termina la tarea.
run_task
Funciona como run en el SDK. Solo se requiere goal.
| Parámetro | Tipo | Valor predeterminado | Descripción |
|---|---|---|---|
goal | string | obligatorio | Qué hay que hacer, en español sencillo, con todos los detalles necesarios para completarlo. |
start_url | string | ninguno | Página que se abre primero. Si no se indica, la tarea encuentra su propio camino a partir del objetivo. |
result_schema | object | libre | JSON Schema de los datos que se devolverán. El resultado incluirá los datos con esa estructura. |
effort | low | medium | high | xhigh | medio | Cuánta capacidad se debe emplear. Un esfuerzo mayor permite gestionar páginas más difíciles y cuesta más. |
max_cost_usd | number | sin límite | Presupuesto en USD que se comprueba entre pasos. El coste total puede superar este importe en el último paso. |
max_steps | integer | 30 | Número máximo de pasos antes de que se detenga la tarea. |
timeout_seconds | integer | 300 | Límite de tiempo total de la tarea. |
secrets | string[] | ninguno | Nombres de los valores privados que la tarea puede escribir. Cada valor se lee de NODEMANTIS_SECRET_<NAME> en el entorno del servidor. |
use_proxy | boolean | false | Enruta el navegador a través del proxy configurado en el entorno del servidor. |
show_browser | boolean | false | Muestra la ventana del navegador mientras se ejecuta la tarea. |
retrieve_data
Funciona como retrieve en el SDK. Usa run_task en su lugar cuando para obtener los datos haya que hacer clic, escribir o recorrer varias páginas.
| Parámetro | Tipo | Valor predeterminado | Descripción |
|---|---|---|---|
url | string | obligatorio | La página que se va a leer. |
prompt | string | obligatorio | Qué se debe leer de la página. |
result_schema | object | libre | JSON Schema de la estructura de los datos devueltos. |
effort | low | medium | high | xhigh | medio | Cuánta capacidad se debe emplear para leer la página. |
use_proxy | boolean | false | Enruta el navegador a través del proxy configurado en el entorno del servidor. |
show_browser | boolean | false | Muestra la ventana del navegador mientras se lee la página. |
get_task
| Parámetro | Tipo | Valor predeterminado | Descripción |
|---|---|---|---|
task_id | string | obligatorio | El task_id devuelto por run_task o retrieve_data. |
wait_seconds | integer | 45 | Cuánto tiempo se espera a que termine la tarea antes de responder. Con 0, responde inmediatamente. |
cancel_task
Recibe un task_id. Si la tarea ya terminó, no se modifica.
Tareas largas
Una tarea en un sitio web puede tardar más de lo que un asistente está dispuesto a esperar en una sola llamada a una herramienta. Por eso, run_task y retrieve_data esperan hasta 45 segundos. Si la tarea termina en ese tiempo, la llamada devuelve el resultado. De lo contrario, devuelve el estado running con un task_id, y la tarea sigue ejecutándose en 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."
}
A continuación, el asistente llama a get_task con ese id hasta que el estado sea succeeded, failed o 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"
}
}
Una tarea failed sigue devolviendo lo que encontró, junto con el motivo, para que el asistente pueda ajustar el objetivo e intentarlo de nuevo. Las tareas terminadas se conservan durante una hora. Las tareas pertenecen al servidor en ejecución: se detienen cuando el asistente cierra el servidor.
Secretos
Las contraseñas y los códigos de un solo uso nunca pasan por la conversación. Define cada valor en el entorno del servidor como NODEMANTIS_SECRET_<NAME>, junto a la clave de API en env. El asistente solo pasa los nombres en secrets y hace referencia a un valor en el objetivo como <secret:NAME>. Consulta Secretos.
Proxy
Para enviar el navegador de una tarea a través de un proxy, define NODEMANTIS_PROXY en el entorno del servidor y haz que la tarea pase use_proxy. Las listas y los archivos de proxy funcionan como se describe en Configuración del proxy.
Opciones del servidor
Añade estas opciones después de mcp en la lista args.
| Parámetro | Tipo | Valor predeterminado | Descripción |
|---|---|---|---|
--wait-seconds <n> | number | 45 | Cuánto tiempo espera una llamada a una herramienta a que termine una tarea antes de devolver el id de la tarea. Redúcelo si tu asistente deja de esperar las llamadas a herramientas antes. |
--max-tasks <n> | number | 4 | Cuántas tareas pueden ejecutarse al mismo tiempo. |
-H, --headed | flag | headless | Muestra la ventana del navegador para todas las tareas, salvo que una llamada a una herramienta establezca show_browser. |
Solución de problemas
- El asistente indica que no hay ninguna clave de API configurada. Añade
NODEMANTIS_API_KEYaenvdel servidor o ejecutanodemantis configureuna vez y vuelve a intentarlo. No hace falta reiniciar después deconfigure. - Se agota el tiempo de espera al iniciar el servidor por primera vez. El primer inicio de
npxdescarga el paquete. Instálalo una vez connpm install -g node-mantise inicia el comando instalado en su lugar:{ "mcpServers": { "node-mantis": { "command": "nodemantis", "args": ["mcp"] } } } - Las tareas no se inician. Ejecuta
nodemantis doctorpara comprobar la instalación, el navegador y la clave de API.