Node Mantis
offiziellWeb-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_taskundcancel_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:
- Kopiere einen API-Schlüssel aus dem Dashboard.
- 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.
- 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-mantisist der Name, den der Assistent für den Server anzeigt. Du kannst ihn ändern.commandundargslegen 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.enventhä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 mitnodemantis configuregespeichert hast, kannst duenvweglassen.
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.
| Assistent | Wo der Eintrag hingehört |
|---|---|
| Claude Code | Ein Befehl in deinem Terminal. |
| Claude Desktop | claude_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. |
| Codex | Ein 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
| Tool | Beschreibung |
|---|---|
run_task | Erledigt 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_task | Wartet auf eine Aufgabe und gibt ihren Status, den neuesten Fortschritt und das Ergebnis zurück. |
cancel_task | Stoppt 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.
| Parameter | Typ | Standard | Beschreibung |
|---|---|---|---|
goal | string | erforderlich | Was erreicht werden soll, in einfachem Deutsch und mit allen Details, die für den Abschluss nötig sind. |
start_url | string | keiner | Seite, die zuerst geöffnet werden soll. Ohne diese Angabe findet die Aufgabe anhand des Ziels selbst den Weg. |
result_schema | object | frei wählbar | JSON Schema für die zurückzugebenden Daten. Das Ergebnis enthält die Daten dann in dieser Form. |
effort | low | medium | high | xhigh | mittel | Wie viel Leistung eingesetzt werden soll. Ein höherer Aufwand kann schwierigere Seiten bewältigen und kostet mehr. |
max_cost_usd | number | kein Limit | Budget in USD, das zwischen den Schritten geprüft wird. Der letzte Schritt kann dazu führen, dass die Gesamtausgaben diesen Betrag überschreiten. |
max_steps | integer | 30 | Maximale Anzahl von Schritten, bevor die Aufgabe beendet wird. |
timeout_seconds | integer | 300 | Gesamtzeitlimit für die Aufgabe. |
secrets | string[] | keiner | Namen privater Werte, die die Aufgabe eingeben darf. Jeder Wert wird aus NODEMANTIS_SECRET_<NAME> in der Serverumgebung gelesen. |
use_proxy | boolean | false | Leitet den Browser über den in der Serverumgebung konfigurierten Proxy. |
show_browser | boolean | false | Zeigt 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.
| Parameter | Typ | Standard | Beschreibung |
|---|---|---|---|
url | string | erforderlich | Die zu lesende Seite. |
prompt | string | erforderlich | Was von der Seite gelesen werden soll. |
result_schema | object | frei wählbar | JSON Schema für die Form der zurückgegebenen Daten. |
effort | low | medium | high | xhigh | mittel | Wie viel Leistung für das Lesen der Seite eingesetzt werden soll. |
use_proxy | boolean | false | Leitet den Browser über den in der Serverumgebung konfigurierten Proxy. |
show_browser | boolean | false | Zeigt während des Lesens der Seite das Browserfenster an. |
get_task
| Parameter | Typ | Standard | Beschreibung |
|---|---|---|---|
task_id | string | erforderlich | Die von run_task oder retrieve_data zurückgegebene task_id. |
wait_seconds | integer | 45 | Wie 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.
| Parameter | Typ | Standard | Beschreibung |
|---|---|---|---|
--wait-seconds <n> | number | 45 | Wie 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> | number | 4 | Wie viele Aufgaben gleichzeitig ausgeführt werden können. |
-H, --headed | flag | headless | Zeigt 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_KEYzuenvdes Servers hinzu oder führenodemantis configureeinmal aus und versuche es dann erneut. Nachconfigureist kein Neustart erforderlich. - Beim ersten Start läuft der Server in ein Zeitlimit. Beim ersten Start von
npxwird das Paket heruntergeladen. Installiere es einmalig mitnpm install -g node-mantisund starte stattdessen den installierten Befehl:{ "mcpServers": { "node-mantis": { "command": "nodemantis", "args": ["mcp"] } } } - Aufgaben können nicht gestartet werden. Führe
nodemantis doctoraus, um die Installation, den Browser und den API-Schlüssel zu überprüfen.