MCP Browser Use

Was Sie mit diesem MCP erreichen können

Dieses Projekt zielt darauf ab, KI-Agenten in die Lage zu versetzen, Web-Nutzung, Browser-Automatisierung, Scraping und Automatisierung mit dem Model Context Protocol (MCP) und Selenium durchzuführen.

Die Besonderheit dieses MCP ist, dass es mehrere Agenten verarbeiten kann, die auf mehrere Browser-Fenster zugreifen. Man muss nicht mehrere Docker-Images, VMs oder Computer starten, um mehrere Scraping-Agenten zu haben. Und man kann weiterhin ein einziges Browser-Profil über alle Agenten hinweg verwenden. Jeder Agent hat seine eigenen Fenster und sie stören sich nicht gegenseitig.

Dies macht den Umgang mit mehreren Agenten nahtlos: Starten Sie einfach so viele Agenten, wie Sie möchten, und es funktioniert einfach! Verwenden Sie zwei Claude Code-Instanzen, eine Codex CLI-Instanz, eine Gemini CLI-Instanz und eine fast-agent-Instanz – alles auf einem Computer, alles mit demselben Browser-Profil und alles (einigermaßen) parallel arbeitend.

Unsere Mission ist es, KI-Agenten jede Web-Aufgabe mit minimaler menschlicher Aufsicht erledigen zu lassen – alles basierend auf Anweisungen in natürlicher Sprache.

Related MCP server: Selenium MCP Server

Funktions-Highlights

• HTML-Kürzung: Das MCP ermöglicht es Ihnen, die Kürzung der HTML-Seiten zu konfigurieren. Andere Scraping-MCPs könnten die KI mit Barrierefreiheits-Snapshots oder HTML-Dumps überfordern, die größer als das Kontextfenster sind. Dieses MCP hilft Ihnen, die maximale Seitengröße durch Festlegen der Umgebungsvariablen MCP_MAX_SNAPSHOT_CHARS zu verwalten.

• Mehrere Browser-Fenster und mehrere Agenten: Sie können mehrere Agenten unabhängig voneinander mit diesem MCP verbinden, ohne dass eine Koordination seitens der Agenten erforderlich ist. Jeder Agent kann mit demselben Browser-Profil arbeiten, was hilfreich ist, wenn Logins über Agenten hinweg bestehen bleiben sollen. Jeder Agent erhält sein eigenes Browser-Fenster, sodass sie sich nicht gegenseitig stören. Verwendet die Chrome DevTools Protocol TargetId, um Browser-Fenster zu identifizieren.

Bekannte Einschränkungen

• Iframe-Kontext: Mehrstufige Interaktionen innerhalb von Iframes erfordern die Angabe von iframe_selector für jede Aktion. Der Browser-Kontext wird nach jedem Tool-Aufruf aus Gründen der Zuverlässigkeit zurückgesetzt. Wiederholen Sie bei Iframe-Workflows den Iframe-Selektor-Parameter in jedem click_element-, fill_text- oder debug_element-Aufruf.

Konfiguration / Installation

1. Klonen und eine virtuelle Umgebung erstellen

git clone https://github.com/janspoerer/mcp_browser_use.git
cd mcp_browser_use
python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt

2. Chrome Beta installieren

Wir empfehlen die Verwendung von Chrome Beta (nicht Ihr reguläres Chrome), damit KI-Agenten mit Remote-Debugging ausgeführt werden können, ohne Ihr tägliches Browsen zu stören.

macOS:

brew install --cask google-chrome-beta

Ubuntu / Debian:

wget -q -O - https://dl.google.com/linux/linux_signing_key.pub | sudo apt-key add -
echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" \
    | sudo tee /etc/apt/sources.list.d/google-chrome.list
sudo apt update && sudo apt install -y google-chrome-beta

Windows: Laden Sie Chrome Beta von google.com/chrome/beta herunter und installieren Sie es.

Überprüfen Sie nach der Installation:

google-chrome-beta --version      # Linux
# or
"/Applications/Google Chrome Beta.app/Contents/MacOS/Google Chrome Beta" --version  # macOS

Linux Headless-Server — Xvfb (virtuelle Anzeige)

Chrome benötigt eine Anzeige. Verwenden Sie auf Headless-Linux-Servern (ohne GUI) Xvfb:

sudo apt install -y xvfb

# Start a virtual display on screen :99
Xvfb :99 -screen 0 1920x1080x24 &

# Tell Chrome which display to use
export DISPLAY=:99

Fügen Sie export DISPLAY=:99 zu Ihrer .bashrc oder .profile hinzu, um dies dauerhaft zu machen.

3. Konfigurieren und starten

• Zeigen Sie nach der Installation von Chrome Beta in Ihrer .mcp.json auf die ausführbare Chrome Beta-Datei, wie im Abschnitt „Konfiguration der Umgebungsvariablen“ unten beschrieben.

• Starten Sie den MCP-Server (wenn Sie nicht wissen, wie das geht, lesen Sie den Abschnitt „Wie man (dieses) MCP verwendet“ unten).

Wie man (dieses) MCP verwendet

Bitte lesen Sie die MCP-Dokumentation auf modelcontextprotocol.io.

Bitte beachten Sie, dass Sie alle Abhängigkeiten in der Python-Umgebung installieren müssen, auf die Ihre MCP-Konfigurationsdatei verweist. Wenn Sie beispielsweise auf die ausführbare Datei python oder python3 verweisen, verweisen Sie auf die globale Python-Umgebung. Normalerweise wird bevorzugt, auf eine virtuelle Umgebung zu verweisen, wie zum Beispiel:

/Users/yourname/code/mcp_browser_use/.venv/bin/python

Wenn Sie dieses Repository in Ihren lokalen code-Ordner geklont haben, sollte Ihre MCP-Konfigurationsdatei wie folgt aussehen:

{
    "mcpServers": {
        "mcp_browser_use": {
            "command": "/Users/janspoerer/code/mcp_browser_use/.venv/bin/python",
            "args": [
                "/Users/janspoerer/code/mcp_browser_use/mcp_browser_use"
            ]
        }
    }
}

und sie befindet sich hier (unter macOS): /Users/janspoerer/Library/Application Support/Claude/claude_desktop_config.json.

Bitte lesen Sie die requirements.txt, um zu sehen, welche Abhängigkeiten Sie installieren müssen.

Starten Sie Claude neu, um zu sehen, ob die JSON-Konfiguration gültig ist. Claude führt Sie zu den Fehlerprotokollen für das MCP, falls etwas nicht stimmt.

Wenn die Einrichtung erfolgreich war, sehen Sie ein kleines Hammer-Symbol unten rechts im „Neuer Chat“-Fenster in Claude. Neben dem Hammer steht die Anzahl der Funktionen, die das MCP bereitstellt.

Klicken Sie auf den Hammer, um die verfügbaren Tools zu sehen.

Konfiguration der Umgebungsvariablen

WICHTIG: Definieren Sie alle Umgebungsvariablen in Ihrer .mcp.json-Datei im Projektstammverzeichnis, NICHT in .env-Dateien. Dies stellt eine einzige Quelle der Wahrheit ohne Konflikte sicher.

Empfohlene Konfiguration (Chrome Beta)

Fügen Sie Umgebungsvariablen zum env-Abschnitt Ihrer .mcp.json-Datei hinzu:

{
  "mcpServers": {
    "mcp_browser_use": {
      "type": "stdio",
      "command": "/path/to/.venv/bin/python",
      "args": ["-m", "mcp_browser_use"],
      "env": {
        "BETA_PROFILE_NAME": "SeleniumProfile",
        "BETA_EXECUTABLE_PATH": "/Applications/Google Chrome Beta.app/Contents/MacOS/Google Chrome Beta",
        "BETA_PROFILE_USER_DATA_DIR": "/Users/yourname/Library/Application Support/Google/Chrome Beta",
        "CHROME_REMOTE_DEBUG_PORT": "9225",
        "MCP_HEADLESS": "0",
        "MCP_ENABLE_EXTENSIONS": "1",
        "MAX_SNAPSHOT_CHARS": "10000"
      }
    }
  }
}

Windows-Beispiel:

"env": {
  "BETA_PROFILE_NAME": "SeleniumProfile",
  "BETA_EXECUTABLE_PATH": "C:\\Program Files\\Google\\Chrome Beta\\Application\\chrome.exe",
  "BETA_PROFILE_USER_DATA_DIR": "C:\\Users\\yourname\\AppData\\Local\\Google\\Chrome Beta\\User Data",
  "CHROME_REMOTE_DEBUG_PORT": "9225",
  "MCP_HEADLESS": "0",
  "MCP_ENABLE_EXTENSIONS": "1"
}

Referenz der Umgebungsvariablen

Warum Chrome Beta verwenden?

Die Verwendung von Chrome Beta (oder Canary) verhindert Konflikte mit Ihrem regulären Chrome-Browser:

• KI-Agenten erfordern, dass Chrome mit aktiviertem Remote-Debugging ausgeführt wird

• Ihre normale Chrome-Instanz kann nicht mit Remote-Debugging ausgeführt werden

• Chrome Beta ermöglicht es beiden, auf demselben System zu koexistieren

Profil-Empfehlungen

• Verwenden Sie ein dediziertes Profil wie "SeleniumProfile" (NICHT "Default")

• Dies verhindert Konflikte, wenn Sie Chrome Beta manuell öffnen

• Erweiterungen und Logins bleiben in diesem Profil über Sitzungen hinweg bestehen

• Jeder KI-Agent erhält sein eigenes Browser-Fenster, teilt sich aber das Profil

Verfügbare Tools

Debugging

Überprüfen Sie, ob der Browser läuft, indem Sie diese URL in Ihrem Hauptbrowser (nicht dem automatisierten Browser) aufrufen:

http://127.0.0.1:9223/json/version

Es wird ungefähr so etwas angezeigt, wenn der Browser läuft:

{
   "Browser": "Chrome/140.0.7339.24",
   "Protocol-Version": "1.3",
   "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36",
   "V8-Version": "14.0.365.3",
   "WebKit-Version": "537.36 (@f8765868e23d9ee5209061fc999f6495c525cd13)",
   "webSocketDebuggerUrl": "ws://127.0.0.1:9223/devtools/browser/d8f511eb-947c-4eb1-833d-917212a92394"
}

Sperrdateien und Koordination

Dieses MCP verwendet dateibasierte Sperren, um mehrere Agenten zu koordinieren, die auf dasselbe Browser-Profil zugreifen. Alle Sperrdateien werden zur einfachen Überprüfung im Projektstammverzeichnis unter tmp/mcp_locks/ gespeichert.

Sperrdateitypen

Aktionssperre (<hash>.softlock.json und <hash>.softlock.mutex)

• Stellt sicher, dass jeweils nur ein Agent Browser-Aktionen ausführen kann

• Standard-TTL: 30 Sekunden (konfigurierbar über MCP_ACTION_LOCK_TTL)

• Wird automatisch mit Heartbeat erneuert, während der Agent arbeitet

• Agenten warten bis zu 60 Sekunden auf den Erhalt der Sperre (konfigurierbar über MCP_ACTION_LOCK_WAIT)

Fenster-Registrierung (<hash>.window_registry.json)

• Verfolgt, welcher Agent welches Browser-Fenster besitzt

• Enthält: targetId, windowId, Prozess-PID, Zeitstempel des letzten Heartbeats

• Wird für die Bereinigung verwaister Fenster verwendet: schließt automatisch Fenster von abgestürzten/veralteten Agenten

• Veraltungs-Schwellenwert: 5 Minuten (konfigurierbar über MCP_WINDOW_REGISTRY_STALE_SECS)

Start-Mutex (<hash>.startup.mutex)

• Stellt den Start einer einzelnen Browser-Instanz pro Profil sicher

• Wird während der Koordination des anfänglichen Chrome-Prozessstarts verwendet

Dateiformat: Der <hash> ist ein SHA-256-Hash, der aus dem user_data_dir und dem profile_name Ihres Chrome-Profils abgeleitet wird, was eine stabile Identifizierung über Prozesse hinweg gewährleistet.

Konfiguration

Sie können das Sperrverhalten mit diesen Umgebungsvariablen anpassen:

# Lock directory (default: <project_root>/tmp/mcp_locks/)
MCP_BROWSER_LOCK_DIR=/path/to/locks

# Action lock TTL in seconds (default: 30)
MCP_ACTION_LOCK_TTL=30

# Max wait time for action lock in seconds (default: 60)
MCP_ACTION_LOCK_WAIT=60

# Window registry stale threshold in seconds (default: 300)
MCP_WINDOW_REGISTRY_STALE_SECS=300

# File mutex stale threshold in seconds (default: 60)
MCP_FILE_MUTEX_STALE_SECS=60

Bereinigung verwaister Fenster

Wenn ein Agent eine Browser-Sitzung startet, führt er automatisch Folgendes aus:

1. Überprüft die Fenster-Registrierung auf Einträge von toten Prozessen (PID existiert nicht mehr)

2. Überprüft auf veraltete Einträge (kein Heartbeat seit >5 Minuten)

3. Schließt verwaiste Fenster über das Chrome DevTools Protocol

4. Bereinigt Registrierungseinträge

Dies stellt sicher, dass abgestürzte oder beendete Agenten keine Zombie-Browser-Fenster offen lassen.

Demo-Video (YouTube)

Tests ausführen

Wir möchten pytest-asyncio NICHT verwenden.

pip install -e ".[test]"`