Lass deinen Coding-Agenten den Browser verwenden, in dem du bereits angemeldet bist.

Was wo startet

Dein MCP-Client startet das npm-Paket über stdio als lokalen Kindprozess. Dieser Prozess lauscht nur auf 127.0.0.1:17374. Die Erweiterung verbindet sich damit und führt jede Aufgabe über die Agent-Schleife von WebBrain im ausgewählten Browser-Tab aus.

Der Server ist kein zweiter Browser und kopiert keine Cookies. Er ist eine lokale Übergabestelle zwischen MCP-Client und Erweiterung. Das Browser-Profil – und damit die authentifizierte Sitzung – bleibt immer an Ort und Stelle.

Vor dem Verbinden

Server bei deinem MCP-Client registrieren

Verwende einmal eine der clientspezifischen Konfigurationen unten. Das sind Installationsbefehle, nicht die Art, wie du Browser-Aufgaben anforderst. Nach der Registrierung startet der Client den Server für dich, und du chattest wie gewohnt weiter; betreibe nicht parallel eine manuelle Instanz auf demselben Port.

Codex-App, CLI oder IDE-Erweiterung

codex mcp add webbrain -- npx -y @webbrain/mcp-server

Codex speichert MCP-Server in ~/.codex/config.toml; App, CLI und IDE-Erweiterung teilen sich diese Konfiguration auf demselben Codex-Host. Öffne für lange Browser-Aufgaben diese Datei und gib dem Werkzeug mehr Zeit als das Standard-Budget von Codex pro Aufruf:

[mcp_servers.webbrain]
command = "npx"
args = ["-y", "@webbrain/mcp-server"]
tool_timeout_sec = 360

Starte die App oder IDE-Erweiterung nach der Änderung der Datei neu. Führe im CLI codex mcp list aus, um den Eintrag zu bestätigen, und prüfe in einer Codex-Sitzung mit /mcp den verbundenen Server. Siehe den offiziellen Codex-MCP-Leitfaden für die geteilte Host-Konfiguration und alle unterstützten Optionen.

Claude Code

claude mcp add --transport stdio webbrain -- npx -y @webbrain/mcp-server

Der explizite Transport entspricht der aktuellen Claude-Code-MCP-Konfiguration. Führe nach dem Hinzufügen claude mcp list aus, um den Serverzustand zu prüfen.

Cursor

Füge in den MCP-Einstellungen von Cursor einen lokalen Stdio-Server hinzu oder setze diesen Inhalt in die MCP-JSON-Datei, die Cursor verwendet. Das Format folgt dem Cursor-Format für lokale MCP-Server:

{
  "mcpServers": {
    "webbrain": {
      "command": "npx",
      "args": ["-y", "@webbrain/mcp-server"]
    }
  }
}

OpenCode

Füge diesen Eintrag der Datei ~/.config/opencode/opencode.json hinzu, im Format für lokale MCP-Server von OpenCode:

{
  "mcp": {
    "webbrain": {
      "type": "local",
      "command": ["npx", "-y", "@webbrain/mcp-server"]
    }
  }
}

OpenClaw

Registriere WebBrain in OpenClaw als ausgehenden MCP-Server. Verwende für diese Integration nicht openclaw mcp serve: Dieser Befehl lässt OpenClaw selbst als Server dienen – die Gegenrichtung.

openclaw mcp add webbrain \
  --command npx \
  --arg -y \
  --arg @webbrain/mcp-server \
  --timeout 360

mcp add prüft den Stdio-Server vor dem Speichern. Führe openclaw mcp status --verbose aus, um die gespeicherte Definition zu prüfen. Die normalen Werkzeugprofile coding und messaging enthalten eingerichtete MCP-Server; das Profil minimal, eine explizite bundle-mcp-Ablehnung oder eine Sandbox-Werkzeugrichtlinie kann sie verbergen. Siehe den OpenClaw-MCP-Leitfaden für aktuelle Registry- und Richtlinien-Details.

Manueller Start

Ein manueller Start ist nützlich, um den Listener zu diagnostizieren, aber bei normalem MCP-Gebrauch nicht nötig:

npx -y @webbrain/mcp-server

Lass dieses Terminal offen. Wenn du es schließt, endet der Bridge-Listener. Führe in einem Quellcode-Checkout npm install, npm run build und dann npm start in mcp-server/ aus.

WebBrain auf den lokalen Listener zeigen lassen

1. Starte oder starte deinen MCP-Client neu. Sein WebBrain-Server muss laufen, bevor sich die Erweiterung verbinden kann.
2. Öffne die WebBrain-Einstellungen. Gehe zu Einstellungen → Bridge.
3. Lege die exakte URL fest. Gib ws://127.0.0.1:17374/extension ein.
4. Füge den Kopplungsschlüssel ein. Führe npx -y @webbrain/mcp-server pairing-key in einem Terminal aus (oder öffne ~/.webbrain/bridge-key) und füge den Schlüssel in das Feld Kopplungsschlüssel ein. Der Server vertraut nur einem Browser, der nachweist, diesen Schlüssel zu besitzen. Falls das Feld fehlt, aktualisiere zuerst WebBrain.
5. Aktiviere die Cloud-Brücke. Der Status sollte von „Verbindung wird hergestellt“ auf „Verbunden“ wechseln. Die Bezeichnung ist historisch bedingt: Dieses Ziel ist lokal.
6. Überprüfe die Verbindung Ende-zu-Ende. Bitte deinen MCP-Client, webbrain_connection aufzurufen. „Connected“ belegt, dass Client, lokaler Server, WebSocket-Listener und Erweiterungs-Handshake bereit sind.

Beschreibe die Browser-Aufgabe in natürlicher Sprache

Formuliere die Anfrage in Codex, Claude Code, Cursor, OpenClaw oder OpenCode so, als gibst du sie einem Kollegen weiter. WebBrain zu nennen macht deine Absicht eindeutig; gib die Seite, das erwartete Ergebnis, den Umfang an und ob Änderungen erlaubt sind.

Lesen ohne Seitenänderung

Lies mit WebBrain das bereits in meinem Browser geöffnete Stripe-Dashboard. Liste die fehlgeschlagenen Zahlungen der letzten sieben Tage mit Kunde, Betrag, Währung, Datum und Fehlergrund auf. Ändere nichts.

Vorhersagbares JSON zurückgeben

Extrahiere mit WebBrain alle überfälligen Rechnungen aus dem in meinem Browser geöffneten Dashboard. Gib JSON mit Kunde, Betrag, Währung, Fälligkeitsdatum und Rechnungs-URL zurück. Ändere nichts.

Mit der Seite interagieren

Öffne im Act-Modus von WebBrain den bereits in meinem Browser sichtbaren Kundendatensatz und aktualisiere den Firmennamen auf Acme Europe. Stoppe vor dem endgültigen Absenden oder Bestätigen.

Der Coding-Agent wählt webbrain_run für allgemeines Lesen oder Interagieren und webbrain_extract, wenn strukturierte Daten angefragt werden. Er liefert die Argumente, überwacht den Lauf und präsentiert WebBrains Ergebnis zurück in der Konversation. Der Ask-Modus kann lesen und extrahieren; er kann nicht klicken, tippen, navigieren oder absenden. Der Act-Modus kann interagieren, innerhalb der üblichen WebBrain-Berechtigungen im Browser.

webbrain_run(
  task: "read the open Stripe dashboard and list failed payments from the last 7 days with customer, amount, currency, date, and failure reason",
  mode: "ask"
)

Sage für eine Aufgabe, die interagieren muss, ausdrücklich „Verwende den Act-Modus von WebBrain“ und lass den Browser sichtbar. WebBrain wendet seine üblichen Genehmigungsabfragen je Fähigkeit und Herkunft an.

Die Werkzeuge, die dein MCP-Client für dich nutzt

Üblicherweise wählst du ein Ergebnis, nicht ein Werkzeug. Dein MCP-Client liest diese Beschreibungen, wählt das passende Werkzeug, füllt dessen Eingaben aus deiner Anfrage und behandelt nachfolgende Aufrufe. Diese Referenz hilft dir, dieses Verhalten zu verstehen oder zu debuggen.

Strukturiertes JSON anfordern

Im normalen Gebrauch sagst du, was extrahiert werden soll, und nennst die gewünschten Felder: „Extrahiere mit WebBrain alle überfälligen Rechnungen aus dem geöffneten Dashboard und gib JSON mit Kunde, Betrag, Währung, Fälligkeitsdatum und Rechnungs-URL zurück.“ Ein fähiger MCP-Client kann diese Felder in das benötigte Schema übersetzen und webbrain_extract für dich aufrufen.

Das Funktionsbeispiel unten zeigt den gleichwertigen Werkzeugaufruf für Client-Entwickler und Debugging. Beschreibe die Auswahllogik in task; beschreibe die Ausgabeform nur in output_schema.

webbrain_extract(
  task: "extract every overdue invoice visible in this account; preserve the displayed currency and use ISO dates where the page provides a full date",
  output_schema: {
    type: "object",
    properties: {
      invoices: {
        type: "array",
        items: {
          type: "object",
          properties: {
            customer: { type: "string" },
            amount: { type: "number" },
            currency: { type: "string" },
            due_date: { type: "string" },
            invoice_url: { type: "string" }
          },
          required: ["customer", "amount", "currency", "due_date"]
        }
      }
    },
    required: ["invoices"]
  }
)

• Verwende einen Objekt-Stamm mit expliziten properties- und required-Feldern.
• Fordere nur die engsten Daten an, die du brauchst. Ein Schema gewährt keinen Zugriff auf Daten, die die Browser-Sitzung nicht sieht.
• Das Werkzeug ist schreibgeschützt, aber Seitentext und Ergebnis gehen dennoch an den in WebBrain konfigurierten LLM-Anbieter.
• Ist das Ergebnis für den gespeicherten Schnappschuss des Laufs zu groß, meldet der Status möglicherweise, dass das gespeicherte Ergebnis gekürzt wurde. Verkleinere die Anfrage und versuche es erneut.

Den Lebenszyklus eines Laufs verstehen

Die meisten MCP-Clients verwalten diesen Lebenszyklus für dich: Sie warten auf das Ergebnis, zeigen WebBrains Klärungsfrage an, wenn menschliche Eingabe nötig ist, und fahren mit deiner Antwort fort. Die expliziten Aufrufe unten sind nützlich für Client-Entwickler, zur Fehlerbehebung oder wenn du den Client bewusst eine lange Aufgabe im Hintergrund starten lässt.

Aufrufe im Vordergrund warten standardmäßig. Bei langer Arbeit kann der Client wait: false setzen und mit webbrain_status abfragen.

# Referenz auf Werkzeug-Ebene
# Start ohne Warten
webbrain_run(task: "compare the invoices across all visible pages", mode: "ask", wait: false)

# Zurückgegebene ID abfragen
webbrain_status(run_id: "mcp_…")

Ein Timeout eines WebBrain-Laufs gibt die Kontrolle an den MCP-Client zurück, bricht die Browser-Aufgabe aber bewusst nicht ab. Frage den zurückgegebenen run_id ab. So verhindert man, dass ein Timeout eine Aufgabe still beendet, die möglicherweise bereits eine wesentliche Aktion ausgeführt hat.

Wenn WebBrain eine Frage stellt

Der pausierte Schnappschuss enthält eine für Menschen lesbare Frage und eine clarify_id. Zeige dem Nutzer diese Frage. Sende seine Antwort wörtlich; rate nicht.

webbrain_respond(
  run_id: "mcp_…",
  clarify_id: "clarify_…",
  answer: "Use the Acme EU account."
)

Wähle die kleinste Berechtigung

Die Genehmigung des MCP-Clients und die von WebBrain sind getrennte Ebenen. Dein Client fragt möglicherweise vor dem Aufruf von webbrain_run; WebBrain fragt möglicherweise vor einer wesentlichen Aktion auf einem Ursprung. Die eine Genehmigung ersetzt nicht die andere.

Sicherheitsgrenzen, die du einhalten solltest

• Halte den Listener lokal. Er ist an 127.0.0.1 gebunden. Leite Port 17374 nicht weiter, veröffentliche ihn nicht über eine Container-Brücke und proxy ihn nicht ins Netzwerk.
• Bewahre den Kopplungsschlüssel sicher auf. Loopback allein ist keine Authentifizierung; der Server vertraut einem Socket erst, nachdem dieser eine Einmal-Herausforderung mit einem HMAC beantwortet hat, der mit dem Kopplungsschlüssel signiert ist; der Schlüssel selbst geht nie über den Socket. Wer ~/.webbrain/bridge-key lesen kann, darf koppeln – füge den Schlüssel also nicht in einen Chat ein. Die Erweiterung authentifiziert den Server nicht; behandle lokalen Code und MCP-Pakete weiterhin als vertrauenswürdige Software.
• Nutze zuerst Ask. Schreibgeschützte Arbeit ist leichter zu prüfen und hat eine geringere Schadensreichweite.
• Halte den Browser im Act-Modus sichtbar. Du kannst den Lauf im Seitenpanel stoppen, und unerwartete Navigation oder Eingaben sind ein Grund zum Stoppen.
• Denke an die Anbietergrenze. Die MCP-Brücke bleibt lokal, aber Seiteninhalte werden an den in WebBrain konfigurierten Modellanbieter gesandt. Verwende ein lokales Modell, wenn Inhalte auf dem Gerät bleiben müssen.
• Verwechsle einen Timeout nicht mit einem Rollback. Ein Abbruch stoppt künftige Schritte; er kann eine gesendete E-Mail, ein abgesandtes Formular, einen Kauf oder eine andere abgeschlossene Aktion nicht rückgängig machen.

Das vollständige Design findest du im Sicherheitsmodell, im Dokument zu Datenschutz und Datenfluss sowie im Leitfaden zu Modi, Sicherheit und Datenschutz.

Fehlerbehebung nach Symptom

Umgebungskonfiguration

Setze Umgebungsvariablen für einen Stdio-Client in dessen MCP-Konfiguration. Wenn du Port oder Pfad änderst, aktualisiere die Cloud-Brücken-URL in den WebBrain-Einstellungen exakt entsprechend.

Du nutzt LM Studio?

LM Studio verwendet das separate WebBrain Web Tools Plugin, nicht dieses MCP-Paket. Dessen Werkzeuge fetch_url und research_url können öffentliche Seiten ohne die Browser-Erweiterung lesen; seine Browser-Werkzeuge können ein Ziel über Port 17375 an deine angemeldete Chromium-Sitzung delegieren.

Was dieser Server bewusst nicht tut

• Er startet keinen Headless-Browser und erstellt kein neues Browser-Profil.
• Er funktioniert nicht über den Firefox-Build.
• Er exportiert keine Cookies, Zugangsdaten oder Session-Speicher.
• Er exponiert die etwa fünfzig Klick-, Eingabe-, Frame-, Screenshot-, Netzwerk- und DOM-Primitive von WebBrain nicht direkt an den MCP-Client.
• Er macht die Brücke nicht sicher für eine Fernnutzung.
• Er beseitigt nicht die Notwendigkeit eines konfigurierten Modells in WebBrain.

Wenn du deterministische Browser-Automatisierung auf niedriger Ebene in einem isolierten Profil brauchst, passt ein MCP-Server im Playwright-Stil vielleicht besser. Verwende WebBrain MCP, wenn die entscheidende Anforderung deine vorhandene angemeldete Browser-Sitzung plus WebBrains Sicherheitsmodell im Browser ist.