stealth-browser-mcp

Ein MCP-Server, der einem KI-Assistenten einen echten Chrome-Browser zur Verfügung stellt, der angemeldet bleibt.

Die meisten Browser-Automatisierungstools geben dem Modell einen frischen, leeren Browser. Dieser hier steuert ein persistentes Chrome-Profil, sodass das Modell, sobald du dich selbst auf einer Website angemeldet hast – egal ob mit 2FA, CAPTCHA oder Gerätefreigabe – diese Sitzung auch bei späteren Läufen weiterverwenden kann, ohne jemals dein Passwort zu sehen.

Für Websites, die eine skriptgesteuerte Anmeldung nicht tolerieren, bietet er zwei Notluken: Anmeldedaten, die zum Ausfüllzeitpunkt aus dem macOS-Schlüsselbund gezogen werden, und WebAuthn-Passkeys, die über den virtuellen Authentifikator von Chrome abgespielt werden.

[!WARNUNG] Dies ist ein Werkzeug für Profis. Es gibt einem Sprachmodell die Kontrolle über einen Browser, der deine aktiven Sitzungen enthält, und es ist in der Lage, deine gespeicherten Passwörter in Seiten einzutippen, die das Modell auswählt. Lies SECURITY.md und Verantwortungsvoller Umgang, bevor du es auf etwas richtest, das dir wichtig ist.

Inhalt

• So funktioniert es

• Voraussetzungen

• Installation

• Mit einem MCP-Client verbinden

• Die erste Anmeldung

• Tool-Referenz

• Anmeldedaten im Schlüsselbund speichern

• Passkeys

• Konfiguration

• Stealth verifizieren

• Fehlerbehebung

• Verantwortungsvoller Umgang

• Lizenz

Related MCP server: agent-browser-mcp

So funktioniert es

        MCP client (Claude Code, Claude Desktop, Cursor, …)
                          │
                          │  JSON-RPC over stdio
                          ▼
              ┌───────────────────────────┐
              │   stealth-browser-mcp     │
              │   16 tools, one browser   │
              └─────┬───────────────┬─────┘
                    │               │
     credentials    │               │   CDP + Puppeteer
                    ▼               ▼
        ┌───────────────────┐   ┌───────────────────────┐
        │  macOS Keychain   │   │  Google Chrome        │
        │  stealth-mcp:*    │   │  + stealth plugin     │
        │  passwords,       │   │  + WebAuthn virtual   │
        │  passkey material │   │    authenticator      │
        └───────────────────┘   └───────────┬───────────┘
                                            │
                                            ▼
                              ┌─────────────────────────┐
                              │  Persistent profile dir │
                              │  cookies · localStorage │
                              │  IndexedDB · sessions   │
                              └─────────────────────────┘

Drei Komponenten leisten die Arbeit:

Persistenz. Chrome wird mit einem festen userDataDir gestartet statt mit einem Wegwerf-Verzeichnis. Melde dich einmal interaktiv an und die Cookies überleben jeden späteren Lauf – der übliche Grund, warum Automatisierung auf echten Websites scheitert, verschwindet.

Stealth. puppeteer-extra-plugin-stealth patcht die bekannten Automatisierungs-Merkmale, und der Server legt noch ein paar weitere obendrauf: navigator.webdriver ist undefined, window.chrome.runtime ist vorhanden, HeadlessChrome wird aus dem User-Agent entfernt, und --disable-blink-features=AutomationControlled wird gesetzt. Klicks bewegen die Maus entlang eines Pfads zu einem verrauschten Punkt innerhalb des Ziels; getippt wird Zeichen für Zeichen mit 30–100 ms Abständen.

Wiederverwendung statt Erstellung von Sitzungen. Das Designziel ist, die Automatisierung von Anmeldungen ganz zu vermeiden. Schlüsselbund-Autofill und Passkey-Wiedergabe existieren für die Fälle, in denen das nicht möglich ist.

Voraussetzungen

• Node.js 18 oder neuer

• Google Chrome. Das gebündelte Chromium von Puppeteer funktioniert, aber ein echtes Chrome-Build ist deutlich schwerer zu erkennen.

• macOS, wenn du die Schlüsselbund- und Passkey-Funktionen nutzen möchtest. Alles andere – Navigation, Extraktion, Screenshots, das persistente Profil – ist plattformübergreifend. Die Schlüsselbund-Ebene ruft /usr/bin/security auf und schlägt auf anderen Plattformen fehl; die Browser-Tools fassen es nicht an.

Installation

git clone https://github.com/lauyuen/stealth-browser-mcp.git
cd stealth-browser-mcp
npm install

Optional kannst du die Beispiel-Umgebungsdatei kopieren und bearbeiten:

cp .env.example .env

Bestätige, dass der Browser startet und die Umgehungen aktiv sind:

npm run check-stealth

Mit einem MCP-Client verbinden

Der Server spricht stdio. Richte deinen Client mit einem absoluten Pfad auf src/server.js aus.

Claude Code

claude mcp add stealth-browser -- node /absolute/path/to/stealth-browser-mcp/src/server.js

Claude Desktop – ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "stealth-browser": {
      "command": "node",
      "args": ["/absolute/path/to/stealth-browser-mcp/src/server.js"]
    }
  }
}

Jeder andere MCP-Client – gleiche Struktur, plus optionaler Profil-Override:

{
  "mcpServers": {
    "stealth-browser": {
      "command": "node",
      "args": ["/absolute/path/to/stealth-browser-mcp/src/server.js"],
      "env": {
        "BROWSER_PROFILE_DIR": "/absolute/path/to/a/private/profile/dir"
      }
    }
  }
}

Starte den Client danach neu. browser_status ist der schnellste Weg, um zu bestätigen, dass die Verbindung aktiv ist.

Die erste Anmeldung

Bevor das Modell eine Website nutzen kann, musst du das Profil selbst vorbereiten:

npm run login -- https://example.com

Ein sichtbares Chrome-Fenster öffnet sich mit demselben Profil, das auch der MCP-Server verwenden wird. Melde dich normal an – Passwortmanager, 2FA-Aufforderungen, CAPTCHAs, „Dieses Gerät merken", alles davon. Drücke Enter im Terminal, wenn du fertig bist, und die Sitzung wird auf die Festplatte geschrieben.

Jeder spätere MCP-Lauf erbt diese Sitzung. Wiederhole das pro Website. Sitzungen laufen nach dem eigenen Zeitplan der Website ab, also führe dies erneut aus, wenn eine Website dich abmeldet.

Tool-Referenz

Navigation und Interaktion

Seite lesen

Sitzung und Authentifizierung

Browser-Lebenszyklus

Der Browser startet standardmäßig headless und wird über Aufrufe hinweg wiederverwendet. browser_open_interactive_window ist das einzige Tool, das ihn in ein sichtbares Fenster umschaltet.

Anmeldedaten im Schlüsselbund speichern

Passwörter liegen im macOS-Schlüsselbund unter dem Dienstpräfix stealth-mcp: – niemals in einer Datei in diesem Repository und niemals im Kontext des Modells.

npm run keychain set github you@example.com     # prompts; input is not echoed
npm run keychain get github you@example.com     # confirms presence, prints length only
npm run keychain delete github you@example.com

Das Modell löst dann eine Anmeldung aus, ohne das Geheimnis jemals zu erfahren:

// browser_autofill_login
{
  "service": "github",
  "account": "you@example.com",
  "usernameSelector": "#login_field",
  "passwordSelector": "#password",
  "submitSelector": "input[type='submit']"
}

service ist ein beliebiges Label, das du wählst – es muss nur zwischen CLI und Tool-Aufruf übereinstimmen.

Du kannst das Passwort für Skriptzwecke auch als abschließendes CLI-Argument übergeben, aber es landet dann in deinem Shell-Verlauf und in der Prozessliste, weshalb der Befehl dich warnt, wenn du das tust.

Passkeys

Chrome stellt über das DevTools-Protokoll einen WebAuthn-virtuellen Authentifikator bereit – einen Software-Authentifikator, der zum Testen von WebAuthn-Abläufen gedacht ist. Dieser Server steuert ihn und persistiert das resultierende Schlüsselmaterial im Schlüsselbund, sodass es Läufe überdauert.

Registrieren eines Automatisierungs-Passkeys

1. passkey_enable_virtual_authenticator ohne Argumente aufrufen.

2. Navigiere zum „Passkey hinzufügen"-Ablauf der Website und schließe ihn ab. Der virtuelle Authentifikator beantwortet die Challenge; es erscheint keine OS-Aufforderung.

3. passkey_save_registration mit der rpId der Website und deinem Konto aufrufen.

Spätere Verwendung

passkey_enable_virtual_authenticator mit rpId und account injiziert die gespeicherte Anmeldedaten, bevor du navigierst, und die Website meldet dich ohne Aufforderung an.

[!VORSICHT] Ein so gehaltener Passkey ist eine Datei, kein Hardware-Schlüssel. Er kann kopiert werden – genau die Eigenschaft, die echte Passkeys verhindern sollen. Registriere damit nur Automatisierungs-Passkeys. Verwende ihn nicht für den Passkey, der deine E-Mail, deine Bank oder irgendetwas anderes schützt, dessen Verlust schwerwiegend wäre.

Konfiguration

Alle Einstellungen sind Umgebungsvariablen, die aus der Prozessumgebung oder einer .env-Datei gelesen werden. Siehe .env.example.

Chrome-Startflags und das Standard-Viewport von 1280×800 befinden sich in src/config.js. Mehrere Flags tauschen Sicherheit gegen Kompatibilität – SECURITY.md erklärt, welche und warum du sie möglicherweise entfernen möchtest.

Stealth verifizieren

npm run check-stealth

Meldet navigator.webdriver, window.chrome, window.chrome.runtime, die Plugin-Anzahl, navigator.languages und den effektiven User-Agent und gibt dann das aufgelöste Profil und die Chrome-Pfade aus.

Für eine strengere Prüfung richten Sie den Browser auf eine Fingerprinting-Seite — zum Beispiel bot.sannysoft.com oder abrahamjuliot.github.io/creepjs — mit browser_navigate gefolgt von browser_screenshot.

Kein Stealth-Setup ist unerkennbar. Gut verteidigte Websites kombinieren Fingerprinting mit Verhaltensanalyse, IP-Reputation und Kontohistorie und werden Automatisierung trotzdem erkennen. Behandeln Sie dies als „löst die offensichtlichen Prüfungen nicht aus", nicht als Unsichtbarkeit.

Fehlerbehebung

„Failed to launch the browser process" / Profil ist gesperrt. Chrome erlaubt einen Prozess pro Profilverzeichnis. Schließen Sie jedes Chrome, das Sie manuell gegen dasselbe Verzeichnis gestartet haben. Der Server löscht veraltete Singleton*-Sperrdateien beim Start und verbindet sich über seinen DevTools-Port wieder mit einer laufenden Instanz, aber ein laufendes Chrome, das das Profil besitzt, gewinnt.

Eine Website meldet das Modell ab oder blockiert es. Die gespeicherte Sitzung ist abgelaufen. Führen Sie npm run login -- <url> erneut aus.

Selektoren stimmen nicht überein. Rufen Sie browser_extract_html mit einem engen Selektor auf und lassen Sie das Modell das echte Markup lesen, statt zu raten. Single-Page-Apps binden Eingaben oft spät ein — zuerst browser_wait_for verwenden.

Ein CAPTCHA erscheint. Rufen Sie browser_open_interactive_window auf, lösen Sie es selbst und fahren Sie fort. Der gelöste Zustand bleibt im Profil erhalten.

Keychain-Fehler unter Linux oder Windows. Erwartet — diese Ebene ist nur für macOS. Die Browser-Tools funktionieren überall; die Anmeldedaten- und Passkey-Tools nicht.

Verantwortungsvolle Nutzung

Dieses Projekt existiert, damit ein Assistent auf Websites agieren kann, auf denen Sie bereits ein Konto haben, mit Sitzungen, die Sie selbst eingerichtet haben. Das ist der beabsichtigte Umfang, und das Design mit persistentem Profil spiegelt das wider.

Anti-Erkennung und Anmeldedaten-Automatisierung können offensichtlich auch anderswohin gerichtet werden. Bevor Sie es gegen eine Website ausführen, bedenken Sie:

• Die Nutzungsbedingungen der Website. Viele verbieten automatisierten Zugriff ausdrücklich. Das Umgehen einer Bot-Abwehr kann einen Vertrag verletzen, dem Sie zugestimmt haben, und in manchen Rechtsräumen zieht unbefugter Zugriff strafrechtliche Haftung nach sich. In der Lage zu sein, eine Kontrolle zu umgehen, ist keine Erlaubnis dazu.

• Einwilligung. Automatisieren Sie Konten, die Ihnen gehören oder für die Sie eine schriftliche Autorisierung haben, in deren Namen zu handeln. Die Anmeldedaten einer anderen Person in Ihrer Keychain sind keine Einwilligung.

• Last. Begrenzen Sie Ihre Rate. Respektieren Sie robots.txt, wo es gilt. Automatisierung, die eine Website echtes Geld kostet, ist ein guter Weg, die Technik für alle sperren zu lassen.

• Daten anderer Personen. Seiten, die das Modell liest, fließen in den Provider Ihres MCP-Clients. Leiten Sie keine persönlichen Informationen Dritter darüber.

Beiträge, die in erster Linie dazu dienen, den Schutz einer bestimmten Website zu umgehen, Anmeldedaten zu ernten oder Missbrauch zu skalieren, werden nicht übernommen.

Lizenz

MIT © Yuen Lau