Node Mantis

offiziell

Web-Automatisierung: Beschreiben Sie eine Website-Aufgabe in einfachem Englisch. Node Mantis arbeitet die Aufgabe auf der Webseite in einem echten Browser ab und gibt strukturierte Daten zurück.

Was kann man mit Node Mantis MCP machen?

  • Website-Aufgaben ausführen — Gib ein Ziel in einfachem Deutsch an, und Node Mantis klickt, tippt und füllt Formulare in einem echten Browser aus.
  • Strukturierte Daten zurückgeben — Gib ein JSON Schema an und erhalte das Aufgabenergebnis als Daten in der passenden Struktur.
  • Eine einzelne Seite lesen — Verwende retrieve_data, um bestimmte Informationen aus einer URL zu extrahieren, ohne etwas zu ändern.
  • Länger laufende Aufgaben verwalten — Prüfe den Fortschritt einer Hintergrundaufgabe oder stoppe sie mit get_task und cancel_task.
  • Geheimnisse aus dem Chat heraushalten — Verweise mit <secret:NAME> auf gespeicherte Werte, damit Passwörter und Codes niemals im Gespräch auftauchen.

Dokumentation

MCP-Server

Node Mantis enthält einen Model Context Protocol-Server (MCP). Füge ihn einem KI-Assistenten hinzu, der MCP unterstützt, z. B. Claude Code, Claude Desktop, Cursor, VS Code oder Codex. Dann kann der Assistent Aufgaben auf Websites für dich erledigen: Er beschreibt die Aufgabe, Node Mantis arbeitet sie in einem echten Browser auf der Website ab und gibt das Ergebnis als strukturierte Daten zurück.

Wenn du den Server zu deinem Coding-Agenten oder Assistenten hinzufügst, kannst du:

  • Website-Aufgaben erledigen. Gib ein Ziel in einfachem Deutsch an, und Node Mantis arbeitet es auf der Website so ab wie ein echter Nutzer: durch Klicken, Tippen und Ausfüllen von Formularen, Dropdown-Menüs und Datumsauswahlen.
  • Strukturierte Ergebnisse erhalten. Gib ein JSON Schema an, und Node Mantis gibt das Ergebnis als Daten zurück, die diesem Schema entsprechen.
  • Lange Aufgaben im Hintergrund ausführen. Eine Aufgabe, die Minuten dauert, läuft weiter, während dein Assistent ihren Status abfragt, Fortschritte meldet oder sie abbricht.

Der Server ist im Paket node-mantis auf npm und PyPI enthalten, du musst also nichts separat installieren. Dein Assistent startet ihn mit einem einzigen Befehl über Node.js:

npx -y node-mantis mcp

oder über Python mit uv:

uvx node-mantis mcp

Beide Varianten stellen dem Assistenten dieselben Tools zur Verfügung. Du benötigst Node.js oder Python, Google Chrome und einen API-Schlüssel aus dem Dashboard. Wenn Chrome nicht installiert ist, lädt die erste Aufgabe Chrome for Testing herunter.

Zu deinem Assistenten hinzufügen

Jeder Assistent verwaltet in seinen Einstellungen eine Liste von MCP-Servern. Füge dort einen Eintrag für Node Mantis hinzu, entweder mit einem Befehl oder durch Bearbeiten der Einstellungsdatei des Assistenten. Der Assistent startet den Server dann bei Bedarf selbst. Das geht in drei Schritten:

  1. Kopiere einen API-Schlüssel aus dem Dashboard.
  2. Füge den folgenden Eintrag zu deinem Assistenten hinzu. Wo er hingehört, hängt vom Assistenten ab. Siehe die Tabelle und die folgenden Abschnitte.
  3. Starte den Assistenten neu und prüfe, ob alles funktioniert.

Die meisten Assistenten verwenden denselben JSON-Eintrag. Mit Node.js:

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

Mit Python:

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

Der Eintrag besteht aus drei Teilen:

  • node-mantis ist der Name, den der Assistent für den Server anzeigt. Du kannst ihn ändern.
  • command und args legen fest, wie der Assistent den Server startet. Verwende entweder die Node.js- oder die Python-Variante. Beide stellen dem Assistenten dieselben Tools zur Verfügung.
  • env enthält Einstellungen, die der Assistent beim Start an den Server übergibt. Ersetze den Platzhalter durch deinen API-Schlüssel. Wenn du bereits einen Schlüssel mit nodemantis configure gespeichert hast, kannst du env weglassen.

Wenn die Einstellungsdatei bereits einen Abschnitt mcpServers enthält, füge den Eintrag node-mantis dort neben den anderen Einträgen ein, anstatt einen zweiten mcpServers einzufügen.

AssistentWo der Eintrag hingehört
Claude CodeEin Befehl in deinem Terminal.
Claude Desktopclaude_desktop_config.json, über die Einstellungen geöffnet.
Cursor~/.cursor/mcp.json für jedes Projekt oder .cursor/mcp.json in einem einzelnen Projekt.
VS Code.vscode/mcp.json in deinem Workspace.
CodexEin Befehl in deinem Terminal oder ~/.codex/config.toml.

Claude Code

Führe einen dieser Befehle in deinem Terminal aus. Mit Node.js:

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

Mit Python:

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

claude mcp list zeigt dann node-mantis als verbunden an.

Claude Desktop

Öffne Einstellungen, dann Entwickler und anschließend Konfiguration bearbeiten. Dadurch wird claude_desktop_config.json geöffnet. Die Datei befindet sich unter ~/Library/Application Support/Claude/ auf macOS und unter %APPDATA%\Claude\ auf Windows. Füge den obigen JSON-Eintrag hinzu, speichere die Datei und starte die App neu.

Cursor

Füge den obigen JSON-Eintrag zu ~/.cursor/mcp.json hinzu, um ihn in jedem Projekt zu verwenden, oder zu .cursor/mcp.json innerhalb eines einzelnen Projekts. Erstelle die Datei, falls sie noch nicht existiert.

VS Code

VS Code verwendet servers anstelle von mcpServers. Füge Folgendes zu .vscode/mcp.json in deinem Workspace hinzu:

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

Für Python setze command auf uvx und args auf ["node-mantis", "mcp"].

Codex

Führe einen dieser Befehle in deinem Terminal aus. Mit Node.js:

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

Mit Python:

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

Oder bearbeite ~/.codex/config.toml. Das längere Startzeitlimit gibt dem ersten Start Zeit, das Paket herunterzuladen:

[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>"

Für Python setze command auf "uvx" und args auf ["node-mantis", "mcp"].

Python ohne uv

Die obigen Python-Beispiele verwenden uv, das das Paket bei der ersten Verwendung von PyPI abruft. Ohne uv installierst du das Paket einmalig mit python -m pip install node-mantis und verwendest nodemantis als Befehl mit mcp als einzigem Argument:

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

Prüfen, ob alles funktioniert

Nach einem Neustart führt der Assistent node-mantis mit vier Tools unter seinen MCP-Servern auf. Bitte ihn dann um eine Aufgabe, zum Beispiel:

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

Der Assistent ruft run_task auf und antwortet mit den Ergebnissen der Aufgabe. Falls das nicht funktioniert, siehe Fehlerbehebung.

Windows

Wenn der Assistent npx nicht direkt starten kann, führe es über cmd aus:

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

Tools

ToolBeschreibung
run_taskErledigt eine Website-Aufgabe anhand eines Ziels in einfachem Deutsch: navigieren, klicken, tippen, Formulare ausfüllen und das Ergebnis lesen.
retrieve_dataÖffnet eine Seite und liest Daten daraus, ohne etwas daran zu ändern.
get_taskWartet auf eine Aufgabe und gibt ihren Status, den neuesten Fortschritt und das Ergebnis zurück.
cancel_taskStoppt eine laufende Aufgabe und schließt den Browser.

Jede Aufgabe läuft in einer eigenen, neuen Browsersitzung ohne gespeicherte Anmeldedaten. Die Sitzung wird beendet, sobald die Aufgabe abgeschlossen ist.

run_task

Funktioniert wie run im SDK. Nur goal ist erforderlich.

ParameterTypStandardBeschreibung
goalstringerforderlichWas erreicht werden soll, in einfachem Deutsch und mit allen Details, die für den Abschluss nötig sind.
start_urlstringkeinerSeite, die zuerst geöffnet werden soll. Ohne diese Angabe findet die Aufgabe anhand des Ziels selbst den Weg.
result_schemaobjectfrei wählbarJSON Schema für die zurückzugebenden Daten. Das Ergebnis enthält die Daten dann in dieser Form.
effortlow | medium | high | xhighmittelWie viel Leistung eingesetzt werden soll. Ein höherer Aufwand kann schwierigere Seiten bewältigen und kostet mehr.
max_cost_usdnumberkein LimitBudget in USD, das zwischen den Schritten geprüft wird. Der letzte Schritt kann dazu führen, dass die Gesamtausgaben diesen Betrag überschreiten.
max_stepsinteger30Maximale Anzahl von Schritten, bevor die Aufgabe beendet wird.
timeout_secondsinteger300Gesamtzeitlimit für die Aufgabe.
secretsstring[]keinerNamen privater Werte, die die Aufgabe eingeben darf. Jeder Wert wird aus NODEMANTIS_SECRET_<NAME> in der Serverumgebung gelesen.
use_proxybooleanfalseLeitet den Browser über den in der Serverumgebung konfigurierten Proxy.
show_browserbooleanfalseZeigt während der Aufgabe das Browserfenster an.

retrieve_data

Funktioniert wie retrieve im SDK. Verwende stattdessen run_task, wenn das Abrufen der Daten Klicks, Eingaben oder mehrere Seiten erfordert.

ParameterTypStandardBeschreibung
urlstringerforderlichDie zu lesende Seite.
promptstringerforderlichWas von der Seite gelesen werden soll.
result_schemaobjectfrei wählbarJSON Schema für die Form der zurückgegebenen Daten.
effortlow | medium | high | xhighmittelWie viel Leistung für das Lesen der Seite eingesetzt werden soll.
use_proxybooleanfalseLeitet den Browser über den in der Serverumgebung konfigurierten Proxy.
show_browserbooleanfalseZeigt während des Lesens der Seite das Browserfenster an.

get_task

ParameterTypStandardBeschreibung
task_idstringerforderlichDie von run_task oder retrieve_data zurückgegebene task_id.
wait_secondsinteger45Wie lange auf den Abschluss der Aufgabe gewartet wird, bevor eine Antwort erfolgt. Bei 0 erfolgt die Antwort sofort.

cancel_task

Erfordert eine task_id. Eine bereits abgeschlossene Aufgabe bleibt unverändert.

Lange Aufgaben

Eine Website-Aufgabe kann länger dauern, als ein Assistent auf einen einzelnen Tool-Aufruf warten möchte. run_task und retrieve_data warten daher bis zu 45 Sekunden. Wird die Aufgabe in dieser Zeit abgeschlossen, gibt der Aufruf das Ergebnis zurück. Andernfalls gibt er den Status running mit einer task_id zurück, und die Aufgabe läuft im Hintergrund weiter:

{
  "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."
}

Der Assistent ruft dann get_task mit dieser ID auf, bis der Status succeeded, failed oder cancelled lautet:

{
  "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"
  }
}

Eine Aufgabe mit dem Status failed gibt weiterhin zurück, was sie gefunden hat, zusammen mit dem Grund, sodass der Assistent das Ziel anpassen und es erneut versuchen kann. Abgeschlossene Aufgaben werden eine Stunde lang aufbewahrt. Aufgaben gehören zum laufenden Server: Sie werden beendet, wenn dein Assistent den Server schließt.

Geheimnisse

Passwörter und Einmalcodes werden niemals über die Unterhaltung übermittelt. Lege jeden Wert in der Serverumgebung als NODEMANTIS_SECRET_<NAME> fest, neben dem API-Schlüssel in env. Der Assistent übergibt nur die Namen in secrets und verweist im Ziel mit <secret:NAME> auf einen Wert. Siehe Geheimnisse.

Proxy

Um den Browser einer Aufgabe über einen Proxy zu leiten, setze NODEMANTIS_PROXY in der Serverumgebung und übergib der Aufgabe use_proxy. Proxy-Listen und -Dateien funktionieren wie unter Proxy-Konfiguration beschrieben.

Serveroptionen

Füge diese nach mcp in der Liste args hinzu.

ParameterTypStandardBeschreibung
--wait-seconds <n>number45Wie lange ein Tool-Aufruf auf eine Aufgabe wartet, bevor er die Aufgaben-ID zurückgibt. Verringere den Wert, wenn dein Assistent Tool-Aufrufe früher abbricht.
--max-tasks <n>number4Wie viele Aufgaben gleichzeitig ausgeführt werden können.
-H, --headedflagheadlessZeigt für jede Aufgabe das Browserfenster an, sofern ein Tool-Aufruf nicht show_browser festlegt.

Fehlerbehebung

  • Der Assistent meldet, dass kein API-Schlüssel konfiguriert ist. Füge NODEMANTIS_API_KEY zu env des Servers hinzu oder führe nodemantis configure einmal aus und versuche es dann erneut. Nach configure ist kein Neustart erforderlich.
  • Beim ersten Start läuft der Server in ein Zeitlimit. Beim ersten Start von npx wird das Paket heruntergeladen. Installiere es einmalig mit npm install -g node-mantis und starte stattdessen den installierten Befehl:
    {
      "mcpServers": {
        "node-mantis": {
          "command": "nodemantis",
          "args": ["mcp"]
        }
      }
    }
    
  • Aufgaben können nicht gestartet werden. Führe nodemantis doctor aus, um die Installation, den Browser und den API-Schlüssel zu überprüfen.