Node Mantis
officielAutomatisation Web : décrivez une tâche sur un site Web en anglais courant ; Node Mantis interagit avec la page Web dans un navigateur réel et renvoie des données structurées.
Que pouvez-vous faire avec Node Mantis MCP ?
- Exécuter des tâches sur des sites web — Indiquez un objectif en français courant, et Node Mantis clique, saisit du texte et remplit des formulaires dans un véritable navigateur.
- Récupérer des données structurées — Fournissez un schéma JSON et obtenez le résultat de la tâche sous forme de données correspondant à cette structure.
- Lire une seule page — Utilisez
retrieve_datapour extraire des informations précises d’une URL sans rien modifier. - Gérer les tâches de longue durée — Vérifiez la progression d’une tâche en arrière-plan ou arrêtez-la avec
get_tasketcancel_task. - Ne pas divulguer de secrets dans le chat — Référencez les valeurs stockées sous la forme
<secret:NAME>afin que les mots de passe et les codes ne soient jamais transmis dans la conversation.
Documentation
Serveur MCP
Node Mantis inclut un serveur Model Context Protocol (MCP). Ajoutez-le à un assistant IA compatible avec MCP, comme Claude Code, Claude Desktop, Cursor, VS Code ou Codex, et l’assistant pourra effectuer des tâches sur des sites web pour vous : il décrit la tâche, Node Mantis parcourt le site dans un véritable navigateur et renvoie le résultat sous forme de données structurées.
L’ajout du serveur à votre agent de programmation ou à votre assistant vous permet de :
- Effectuer des tâches sur des sites web. Indiquez un objectif en français courant et Node Mantis parcourt le site comme le ferait un véritable utilisateur : il clique, saisit du texte et utilise les formulaires, les menus déroulants et les sélecteurs de date.
- Obtenir des résultats structurés. Fournissez un schéma JSON et Node Mantis renvoie des données qui lui correspondent.
- Exécuter de longues tâches en arrière-plan. Une tâche qui prend plusieurs minutes continue de s’exécuter pendant que votre assistant en vérifie l’état, indique sa progression ou l’annule.
Le serveur fait partie du package node-mantis sur npm et PyPI ; aucune installation distincte n’est donc nécessaire. Votre assistant le démarre avec une seule commande, via Node.js :
npx -y node-mantis mcp
ou via Python avec uv :
uvx node-mantis mcp
Les deux donnent accès aux mêmes outils. Vous avez besoin de Node.js ou de Python, de Google Chrome et d’une clé API obtenue depuis le tableau de bord. Si Chrome n’est pas installé, la première tâche télécharge Chrome for Testing.
Ajouter le serveur à votre assistant
Chaque assistant conserve une liste de serveurs MCP dans ses paramètres. Ajoutez une entrée pour Node Mantis, soit avec une commande, soit en modifiant le fichier de paramètres de l’assistant ; celui-ci démarre lui-même le serveur dès qu’il en a besoin. Voici les trois étapes à suivre :
- Copiez une clé API depuis le tableau de bord.
- Ajoutez l’entrée ci-dessous à votre assistant. Son emplacement dépend de l’assistant ; consultez le tableau et les sections suivantes.
- Redémarrez l’assistant et vérifiez que tout fonctionne.
La plupart des assistants utilisent la même entrée JSON. Avec Node.js :
{
"mcpServers": {
"node-mantis": {
"command": "npx",
"args": ["-y", "node-mantis", "mcp"],
"env": { "NODEMANTIS_API_KEY": "sk_live_<copy-from-dashboard>" }
}
}
}
Avec Python :
{
"mcpServers": {
"node-mantis": {
"command": "uvx",
"args": ["node-mantis", "mcp"],
"env": { "NODEMANTIS_API_KEY": "sk_live_<copy-from-dashboard>" }
}
}
}
L’entrée comporte trois parties :
node-mantisest le nom du serveur affiché par l’assistant. Vous pouvez le modifier.commandetargsindiquent comment l’assistant démarre le serveur. Utilisez la version Node.js ou Python ; les deux donnent accès aux mêmes outils.envcontient les paramètres transmis au serveur par l’assistant lors de son démarrage. Remplacez l’espace réservé par votre clé API. Si vous avez déjà enregistré une clé avecnodemantis configure, vous pouvez omettreenv.
Si le fichier de paramètres contient déjà une section mcpServers, ajoutez l’entrée node-mantis à l’intérieur, à côté des autres, au lieu de coller un deuxième mcpServers.
| Assistant | Emplacement de l’entrée |
|---|---|
| Claude Code | Une commande dans votre terminal. |
| Claude Desktop | claude_desktop_config.json, accessible depuis Settings. |
| Cursor | ~/.cursor/mcp.json pour tous les projets, ou .cursor/mcp.json dans un seul projet. |
| VS Code | .vscode/mcp.json dans votre espace de travail. |
| Codex | Une commande dans votre terminal, ou ~/.codex/config.toml. |
Claude Code
Exécutez l’une de ces commandes dans votre terminal. Avec Node.js :
claude mcp add node-mantis -e NODEMANTIS_API_KEY="sk_live_<copy-from-dashboard>" -- npx -y node-mantis mcp
Avec Python :
claude mcp add node-mantis -e NODEMANTIS_API_KEY="sk_live_<copy-from-dashboard>" -- uvx node-mantis mcp
claude mcp list affiche ensuite node-mantis comme connecté.
Claude Desktop
Ouvrez Settings, puis Developer, puis Edit Config. Cela ouvre claude_desktop_config.json, qui se trouve dans ~/Library/Application Support/Claude/ sur macOS et dans %APPDATA%\Claude\ sur Windows. Ajoutez l’entrée JSON ci-dessus, enregistrez le fichier et redémarrez l’application.
Cursor
Ajoutez l’entrée JSON ci-dessus à ~/.cursor/mcp.json pour l’utiliser dans tous les projets, ou à .cursor/mcp.json dans un seul projet. Créez le fichier s’il n’existe pas.
VS Code
VS Code utilise servers au lieu de mcpServers. Ajoutez ceci à .vscode/mcp.json dans votre espace de travail :
{
"servers": {
"node-mantis": {
"type": "stdio",
"command": "npx",
"args": ["-y", "node-mantis", "mcp"],
"env": { "NODEMANTIS_API_KEY": "sk_live_<copy-from-dashboard>" }
}
}
}
Pour Python, définissez command sur uvx et args sur ["node-mantis", "mcp"].
Codex
Exécutez l’une de ces commandes dans votre terminal. Avec Node.js :
codex mcp add node-mantis --env NODEMANTIS_API_KEY="sk_live_<copy-from-dashboard>" -- npx -y node-mantis mcp
Avec Python :
codex mcp add node-mantis --env NODEMANTIS_API_KEY="sk_live_<copy-from-dashboard>" -- uvx node-mantis mcp
Vous pouvez aussi modifier ~/.codex/config.toml. Le délai de démarrage plus long laisse le temps au package d’être téléchargé lors du premier lancement :
[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>"
Pour Python, définissez command sur "uvx" et args sur ["node-mantis", "mcp"].
Python sans uv
Les exemples Python ci-dessus utilisent uv, qui récupère le package depuis PyPI lors de sa première utilisation. Sans uv, installez le package une fois avec python -m pip install node-mantis et utilisez nodemantis comme commande, avec mcp comme seul argument :
{
"mcpServers": {
"node-mantis": {
"command": "nodemantis",
"args": ["mcp"],
"env": { "NODEMANTIS_API_KEY": "sk_live_<copy-from-dashboard>" }
}
}
}
Vérifier que tout fonctionne
Après le redémarrage, l’assistant affiche node-mantis parmi ses serveurs MCP, avec quatre outils. Demandez-lui ensuite d’effectuer une tâche, par exemple :
Use Node Mantis to open https://sandbox.nodemantis.com and tell me the title and price of the first book.
L’assistant appelle run_task et répond en indiquant ce que la tâche a trouvé. Si ce n’est pas le cas, consultez la section Dépannage.
Windows
Si l’assistant ne peut pas démarrer directement npx, lancez-le via cmd :
{
"mcpServers": {
"node-mantis": {
"command": "cmd",
"args": ["/c", "npx", "-y", "node-mantis", "mcp"],
"env": { "NODEMANTIS_API_KEY": "sk_live_<copy-from-dashboard>" }
}
}
}
Outils
| Outil | Description |
|---|---|
run_task | Effectuer une tâche sur un site web à partir d’un objectif formulé en français courant : naviguer, cliquer, saisir du texte, remplir des formulaires et lire le résultat. |
retrieve_data | Ouvrir une page et en lire les données sans rien modifier. |
get_task | Attendre une tâche et renvoyer son état, sa progression la plus récente et son résultat. |
cancel_task | Arrêter une tâche en cours et fermer son navigateur. |
Chaque tâche s’exécute dans une nouvelle session de navigateur, sans identifiants de connexion enregistrés ; la session se ferme à la fin de la tâche.
run_task
Fonctionne comme run dans le SDK. Seul goal est obligatoire.
| Paramètre | Type | Valeur par défaut | Description |
|---|---|---|---|
goal | string | obligatoire | Ce qu’il faut accomplir, en français courant, avec tous les détails nécessaires pour terminer la tâche. |
start_url | string | aucun | Page à ouvrir en premier. Sans cette valeur, la tâche trouve elle-même son chemin à partir de l’objectif. |
result_schema | object | libre | Schéma JSON des données à renvoyer. Le résultat contient alors les données sous cette forme. |
effort | low | medium | high | xhigh | moyen | Niveau de capacité à mobiliser. Un effort plus important permet de traiter des pages plus difficiles et coûte davantage. |
max_cost_usd | number | sans plafond | Budget en USD vérifié entre les étapes. La dernière étape peut porter la dépense totale au-delà de ce montant. |
max_steps | integer | 30 | Nombre maximal d’étapes avant l’arrêt de la tâche. |
timeout_seconds | integer | 300 | Limite de temps totale de la tâche. |
secrets | string[] | aucun | Noms des valeurs privées que la tâche peut saisir. Chaque valeur est lue depuis NODEMANTIS_SECRET_<NAME> dans l’environnement du serveur. |
use_proxy | boolean | false | Fait passer le navigateur par le proxy configuré dans l’environnement du serveur. |
show_browser | boolean | false | Affiche la fenêtre du navigateur pendant l’exécution de la tâche. |
retrieve_data
Fonctionne comme retrieve dans le SDK. Utilisez plutôt run_task lorsque l’accès aux données nécessite des clics, de la saisie ou plusieurs pages.
| Paramètre | Type | Valeur par défaut | Description |
|---|---|---|---|
url | string | obligatoire | Page à lire. |
prompt | string | obligatoire | Éléments à lire sur la page. |
result_schema | object | libre | Schéma JSON définissant la forme des données renvoyées. |
effort | low | medium | high | xhigh | moyen | Niveau de capacité à mobiliser pour lire la page. |
use_proxy | boolean | false | Fait passer le navigateur par le proxy configuré dans l’environnement du serveur. |
show_browser | boolean | false | Affiche la fenêtre du navigateur pendant la lecture de la page. |
get_task
| Paramètre | Type | Valeur par défaut | Description |
|---|---|---|---|
task_id | string | obligatoire | Le task_id renvoyé par run_task ou retrieve_data. |
wait_seconds | integer | 45 | Durée d’attente de la fin de la tâche avant de répondre. La valeur 0 entraîne une réponse immédiate. |
cancel_task
Prend un task_id. Une tâche déjà terminée reste inchangée.
Tâches longues
Une tâche sur un site web peut durer plus longtemps que ce qu’un assistant est prêt à attendre pour un seul appel d’outil. run_task et retrieve_data attendent donc jusqu’à 45 secondes. Si la tâche se termine dans ce délai, l’appel renvoie le résultat. Sinon, il renvoie l’état running avec un task_id, et la tâche continue en arrière-plan :
{
"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."
}
L’assistant appelle ensuite get_task avec cet identifiant jusqu’à ce que l’état soit 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"
}
}
Une tâche failed renvoie tout de même ce qu’elle a trouvé, avec la raison, afin que l’assistant puisse ajuster l’objectif et réessayer. Les tâches terminées sont conservées pendant une heure. Les tâches dépendent du serveur en cours d’exécution : elles s’arrêtent lorsque votre assistant ferme le serveur.
Secrets
Les mots de passe et les codes à usage unique ne transitent jamais par la conversation. Définissez chaque valeur dans l’environnement du serveur sous la forme NODEMANTIS_SECRET_<NAME>, à côté de la clé API dans env. L’assistant ne transmet que les noms dans secrets et fait référence à une valeur dans l’objectif sous la forme <secret:NAME>. Consultez la page Secrets.
Proxy
Pour faire passer le navigateur d’une tâche par un proxy, définissez NODEMANTIS_PROXY dans l’environnement du serveur et demandez à la tâche de transmettre use_proxy. Les listes et fichiers de proxy fonctionnent comme décrit dans Configuration du proxy.
Options du serveur
Ajoutez ces options après mcp dans la liste args.
| Paramètre | Type | Valeur par défaut | Description |
|---|---|---|---|
--wait-seconds <n> | number | 45 | Durée pendant laquelle un appel d’outil attend une tâche avant de renvoyer son identifiant. Réduisez cette valeur si votre assistant abandonne les appels d’outil plus tôt. |
--max-tasks <n> | number | 4 | Nombre de tâches pouvant s’exécuter simultanément. |
-H, --headed | flag | headless | Affiche la fenêtre du navigateur pour chaque tâche, sauf si un appel d’outil définit show_browser. |
Dépannage
- L’assistant indique qu’aucune clé API n’est configurée. Ajoutez
NODEMANTIS_API_KEYàenvdu serveur, ou exécuteznodemantis configureune fois, puis réessayez. Aucun redémarrage n’est nécessaire aprèsconfigure. - Le serveur expire lors de son premier démarrage. Le premier lancement de
npxtélécharge le package. Installez-le une fois avecnpm install -g node-mantiset démarrez plutôt la commande installée :{ "mcpServers": { "node-mantis": { "command": "nodemantis", "args": ["mcp"] } } } - Les tâches ne démarrent pas. Exécutez
nodemantis doctorpour vérifier l’installation, le navigateur et la clé API.