agent-browser-mcp

Ein MCP-Dienst, mit dem dein Agent direkt den „echten Chrome, den du gerade benutzt“ steuern kann.

Es ist kein Sandbox-Browser und kein einfacher Web-Scraper, sondern eine Verbindung zu deinem lokal bereits geöffneten Chrome, wobei Folgendes erhalten bleibt:

• Anmeldestatus

• Cookies

• Geöffnete Tabs

• Echter Seitenkontext

Geeignet für Szenarien wie:

• Hermes direkt deine Xiaohongshu-Feeds, Backend-Systeme, Wissensdatenbanken oder Admin-Seiten lesen lassen

• Automatisierung von bereits angemeldeten Websites, anstatt sich in einem zustandslosen Browser neu anzumelden

• Wechsel zu CDP / echter Maus- und Tastatursteuerung, wenn die normale Browser-Automatisierung instabil ist

• Alles in einem MCP-Tool vereint: Seitenscan, JS-Ausführung, CDP-Steuerung, Screenshots, physische Eingaben

Kurz zusammengefasst:

Dies ist ein Projekt, das „echte Browser-Automatisierung“ als Standard-MCP verpackt, damit Agenten nicht mehr nur Sandbox-Browser bedienen, sondern wirklich in deinen täglichen Browser-Workflow eintauchen können.

Überblick über die Kernfunktionen

• Erkennung und Wechsel von echten Chrome-Tabs

• Seitenscan und vereinfachte Inhaltsextraktion

• Ausführung von JavaScript innerhalb der Seite

• Native CDP-Einzelbefehle / Batch-Aufrufe

• Seiten-Screenshots / Desktop-Screenshots

• Auslesen von Cookies

• Mausbewegungen, Klicks, Drag-and-Drop

• Tastatureingaben und Hotkeys

Wenn du möchtest, dass Hermes, Claude Desktop, Cursor oder andere MCP-Clients deinen echten lokalen Browser direkt steuern, ist dieses Projekt genau das Richtige für dich.

Was kann dieses MCP tun?

Dieses Projekt verpackt echte Browser-Automatisierungsfunktionen in Standard-MCP-Tools. Zu den wichtigsten Fähigkeiten gehören:

1. Browser-Tabs und Navigation

• Anzeigen der aktuell verbundenen echten Tabs

• Wechseln zu einem bestimmten Tab

• Öffnen einer URL im aktuellen Tab

• Öffnen eines neuen Tabs

2. Seiten lesen

• Scannen des aktuellen Seiteninhalts

• Extrahieren von vereinfachtem HTML / Text

• Geeignet zum Lesen von Informations-Feeds, Beitragslisten und Suchergebnisseiten

3. Seitenausführung und CDP-Steuerung

• Ausführen von beliebigem JavaScript auf der Seite

• Direkter Aufruf des Chrome DevTools Protocol (CDP)

• Unterstützung für Einzelbefehle und Batch-Befehle

• Kann für Screenshots, DOM-Abfragen, Klicks, Datei-Uploads und komplexere Vorgänge verwendet werden

4. Screenshot-Funktionen

• Seiten-Screenshot (via CDP)

• Desktop-Screenshot (zur Unterstützung echter Desktop-Operationen)

5. Echte physische Eingaben

• Mausbewegung

• Mausklick

• Maus-Drag

• Tastatureingabe

• Hotkey-Versand

Diese Art von Funktionen eignet sich hervorragend für:

• Websites, bei denen der Anmeldestatus beibehalten werden muss

• Websites, bei denen normale Browser-Automatisierungstools leicht durch Risikokontrollen blockiert werden

• Szenarien, die echte Klicks / echte Tastatureingaben erfordern

• Szenarien, in denen komplexe Seitenstrukturen gelesen werden müssen

Geeignete Szenarien

Zum Beispiel:

• Hermes nutzen, um deinen aktuellen Xiaohongshu-Startseiten-Empfehlungsfeed zu lesen

• Backend-Seiten im echten Browser öffnen und Informationen abgreifen

• CDP nutzen, um Screenshots von Seiten zu machen

• Auf echte Maus-/Tastaturbedienung zurückgreifen, wenn das Seiten-JS nicht ausreicht

• Den Agenten direkt auf deinen bereits angemeldeten Websites arbeiten lassen, anstatt sich in einem zustandslosen Browser neu anzumelden

Funktionsweise

Das Projekt besteht aus drei Schichten:

1. Chrome-Erweiterung

• In echte Webseiten injiziert

• Zugriff auf tabs / cookies / debugger / management über die Chrome-API

• Kommunikation mit dem lokalen Bridge-Dienst

2. TMWebDriver lokale Bridge

• Standard-Listening:

  • WebSocket: 127.0.0.1:18765

  • HTTP: 127.0.0.1:18766

• Verantwortlich für die Verbindung zur Erweiterung, die Sitzungsverwaltung und die Weiterleitung der Ausführungsergebnisse

3. MCP-Dienst

• Stellt Browser-Funktionen als MCP-Tools bereit

• Zur direkten Nutzung durch Clients wie Hermes, Claude Desktop, Cursor usw.

Wichtigste Tools

Die aktuell bereitgestellten MCP-Tools umfassen:

Browser/Tabs

• get_setup_status

• list_tabs

• switch_tab

• open_url

• open_new_tab

• extension_path

• list_extensions

Seiten lesen/ausführen

• scan_page

• execute_js

CDP und Screenshots

• cdp_command

• cdp_batch

• get_cookies

• capture_page_screenshot

• capture_desktop_screenshot

Physische Eingaben

• mouse_move

• mouse_click

• mouse_drag

• type_text

• hotkey

• pointer_info

Installationsvoraussetzungen

Empfohlene Umgebung:

• macOS oder Windows

• Python 3.10+

• Google Chrome

• Ein beliebiger MCP-fähiger Client, zum Beispiel:

  • Hermes Agent

  • Claude Desktop

  • Cursor

Installation

Nach dem lokalen Klonen ausführen:

cd agent-browser-mcp
pip install -e .

Wenn du zuerst ein Wheel bauen und dann installieren möchtest:

python -m pip install --upgrade build
python -m build
pip install dist/agent_browser_mcp-0.1.0-py3-none-any.whl

Befehlszeilen-Tools

Nach der Installation steht ein CLI zur Verfügung:

agent-browser-mcp

Es gibt einige häufig verwendete Unterbefehle:

Chrome-Erweiterungsverzeichnis ausgeben

agent-browser-mcp extension-path

Hermes-Konfigurationsfragment ausgeben

agent-browser-mcp print-hermes-config

Umgebungsdiagnose

agent-browser-mcp doctor

Dieser Befehl gibt JSON aus, um dir bei der Überprüfung zu helfen:

• Speicherort des Erweiterungsverzeichnisses

• Ob config.js generiert wurde

• Port-Status

• Anzahl der aktuell verbundenen Tabs

• Empfehlungen für den nächsten Schritt

Installation der Chrome-Erweiterung

Dieses Projekt enthält eine entpackte Chrome-Erweiterung, die einmal manuell geladen werden muss.

Schritt 1: Erweiterungsverzeichnis abrufen

agent-browser-mcp extension-path

Schritt 2: In Chrome laden

Öffne:

chrome://extensions

Dann:

• „Entwicklermodus“ aktivieren

• Auf „Entpackte Erweiterung laden“ klicken

• Das im vorherigen Schritt ausgegebene Verzeichnis auswählen

Schritt 3: Eine normale Webseite öffnen

Achte darauf, nicht auf about:blank zu bleiben.

Bitte öffne eine normale Webseite in Chrome, zum Beispiel:

• https://www.baidu.com

• https://www.xiaohongshu.com

Andernfalls wird keine gültige Sitzung aufgebaut.

Hermes-Konfiguration

Füge den folgenden Abschnitt zu ~/.hermes/config.yaml hinzu:

mcp_servers:
  agent_browser:
    command: agent-browser-mcp
    timeout: 120
    connect_timeout: 60

Das Projekt enthält auch Beispieldateien:

• examples/hermes-config.yaml

Starte nach der Konfiguration Hermes neu oder lade das MCP neu.

Du kannst es mit dem folgenden Befehl überprüfen:

hermes mcp list
hermes mcp test agent_browser

Wenn der Test erfolgreich ist, kann Hermes diese Browser-Tools finden und aufrufen.

Claude Desktop / Cursor Konfiguration

Im Repository befinden sich auch Beispiele:

• examples/claude-desktop-config.json

• examples/cursor-mcp.json

Die Konfigurationsstruktur ist sehr einfach, der Kern ist:

{
  "mcpServers": {
    "agent_browser": {
      "command": "agent-browser-mcp",
      "args": []
    }
  }
}

Typischer Workflow

1. Python-Paket installieren

2. Erweiterung in Chrome laden

3. Eine echte Webseite öffnen

4. Diesen Dienst im MCP-Client einbinden

5. Browser-Tools aufrufen

Zum Beispiel kann der Agent:

• Die Xiaohongshu-Startseite öffnen

• Den Empfehlungsfeed lesen

• Die Beitragsliste scannen

• Einen CDP-Screenshot der Seite machen

• Bei Bedarf echte Maus-/Tastaturbedienungen ausführen

Sicherheitshinweis

Dieses Projekt steuert deinen echten Browser und deinen echten Desktop.

Das bedeutet:

• Mausbewegungen sind echt

• Klicks sind echt

• Eingaben sind echt

• Hotkeys sind echt

• Der Anmeldestatus im Browser ist ebenfalls echt

Bitte verwende dies nur in MCP-Clients und Agenten-Umgebungen, denen du vertraust.

Häufig gestellte Fragen

1. Hermes sieht den MCP-Dienst, ist aber mit keinem Tab verbunden

Bitte prüfe:

• Ob die Erweiterung bereits in chrome://extensions geladen ist

• Ob in Chrome eine normale Webseite geöffnet ist

• Ob du nur auf about:blank stehst

Du kannst auch Folgendes ausführen:

agent-browser-mcp doctor

2. connected_tabs ist 0

Dies hat normalerweise einen der folgenden Gründe:

• Die Erweiterung wurde nicht erfolgreich geladen

• Es gibt aktuell keine normale Webseite

• Die Erweiterung wurde gerade neu geladen, die Seite wurde noch nicht aktualisiert

Empfehlung:

• Aktuelle Webseite aktualisieren

• Eine neue normale URL öffnen

• doctor erneut ausführen

3. Physische Eingaben funktionieren unter macOS nicht

Bitte erteile dem Terminal / MCP-Client die entsprechenden Systemberechtigungen:

• Bedienungshilfen (Accessibility)

• Bildschirmaufnahme (falls du Desktop-Screenshots benötigst)

4. hermes mcp test agent_browser schlägt fehl

Bitte prüfe:

• Ob das Paket erfolgreich installiert wurde

• Ob agent-browser-mcp im PATH enthalten ist

• Ob die Hermes-Konfiguration korrekt ist

• Führe agent-browser-mcp doctor aus, um die Diagnoseausgabe zu sehen

Danksagung

Die Browser-Automatisierungsfunktionen dieses Projekts wurden aus dem Browser-Stack von GenericAgent extrahiert und als MCP-Dienst neu verpackt.

Besonderer Dank gilt dem GenericAgent-Projekt und seinem Autor für die ursprünglichen Implementierungsideen und die Kernfunktionen.

Ursprüngliche Projektadresse:

• https://github.com/lsdefine/GenericAgent

Die folgenden Teile in diesem Projekt stammen von oder wurden von GenericAgent adaptiert:

• TMWebDriver.py

• simphtml.py

• tmwd_cdp_bridge Chrome-Erweiterungsressourcen

Wenn du auf Basis dieses Projekts weiterentwickelst oder veröffentlichst, wird empfohlen, die Danksagung und den Quellenhinweis für GenericAgent beizubehalten.

Lizenz

MIT