Node Mantis

officiel

Automatisation 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_data pour 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_task et cancel_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 :

  1. Copiez une clé API depuis le tableau de bord.
  2. Ajoutez l’entrée ci-dessous à votre assistant. Son emplacement dépend de l’assistant ; consultez le tableau et les sections suivantes.
  3. 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-mantis est le nom du serveur affiché par l’assistant. Vous pouvez le modifier.
  • command et args indiquent comment l’assistant démarre le serveur. Utilisez la version Node.js ou Python ; les deux donnent accès aux mêmes outils.
  • env contient 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é avec nodemantis configure, vous pouvez omettre env.

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.

AssistantEmplacement de l’entrée
Claude CodeUne commande dans votre terminal.
Claude Desktopclaude_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.
CodexUne 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

OutilDescription
run_taskEffectuer 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_dataOuvrir une page et en lire les données sans rien modifier.
get_taskAttendre une tâche et renvoyer son état, sa progression la plus récente et son résultat.
cancel_taskArrê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ètreTypeValeur par défautDescription
goalstringobligatoireCe qu’il faut accomplir, en français courant, avec tous les détails nécessaires pour terminer la tâche.
start_urlstringaucunPage à ouvrir en premier. Sans cette valeur, la tâche trouve elle-même son chemin à partir de l’objectif.
result_schemaobjectlibreSchéma JSON des données à renvoyer. Le résultat contient alors les données sous cette forme.
effortlow | medium | high | xhighmoyenNiveau de capacité à mobiliser. Un effort plus important permet de traiter des pages plus difficiles et coûte davantage.
max_cost_usdnumbersans plafondBudget en USD vérifié entre les étapes. La dernière étape peut porter la dépense totale au-delà de ce montant.
max_stepsinteger30Nombre maximal d’étapes avant l’arrêt de la tâche.
timeout_secondsinteger300Limite de temps totale de la tâche.
secretsstring[]aucunNoms des valeurs privées que la tâche peut saisir. Chaque valeur est lue depuis NODEMANTIS_SECRET_<NAME> dans l’environnement du serveur.
use_proxybooleanfalseFait passer le navigateur par le proxy configuré dans l’environnement du serveur.
show_browserbooleanfalseAffiche 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ètreTypeValeur par défautDescription
urlstringobligatoirePage à lire.
promptstringobligatoireÉléments à lire sur la page.
result_schemaobjectlibreSchéma JSON définissant la forme des données renvoyées.
effortlow | medium | high | xhighmoyenNiveau de capacité à mobiliser pour lire la page.
use_proxybooleanfalseFait passer le navigateur par le proxy configuré dans l’environnement du serveur.
show_browserbooleanfalseAffiche la fenêtre du navigateur pendant la lecture de la page.

get_task

ParamètreTypeValeur par défautDescription
task_idstringobligatoireLe task_id renvoyé par run_task ou retrieve_data.
wait_secondsinteger45Duré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ètreTypeValeur par défautDescription
--wait-seconds <n>number45Duré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>number4Nombre de tâches pouvant s’exécuter simultanément.
-H, --headedflagheadlessAffiche 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 à env du serveur, ou exécutez nodemantis configure une fois, puis réessayez. Aucun redémarrage n’est nécessaire après configure.
  • Le serveur expire lors de son premier démarrage. Le premier lancement de npx télécharge le package. Installez-le une fois avec npm install -g node-mantis et 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 doctor pour vérifier l’installation, le navigateur et la clé API.