Chrome Browser MCP

Eine lokale Brücke, die es einer privaten ChatGPT-App im Entwicklermodus ermöglicht, die in deinem Desktop-Google-Chrome bereits geöffneten Tabs zu untersuchen und zu steuern.

Aktuelle Patch-Version: 0.1.2. Jeder Patch muss diese Version erhöhen; CI lehnt Patches ab, die das nicht tun.

Die Brücke stellt 17 MCP-Werkzeuge bereit:

• Lesen: browser_status, list_tabs, get_active_tab, read_tab, read_tabs, search_tabs

• Aktionen: click, type, fill_form, press_key, scroll, select_option, navigate, new_tab, close_tab

• ChatGPT-Child-Agenten: spawn_chatgpt_agent, read_chatgpt_agent

spawn_chatgpt_agent öffnet standardmäßig einen neuen chatgpt.com-Tab im Hintergrund, übermittelt exakt den vom Benutzer bereitgestellten Prompt und gibt dessen Tab-ID zurück. read_chatgpt_agent liest diesen Child-Tab über denselben eingeschränkten semantischen Extraktor, der auch für normale Tabs verwendet wird; ruf es später erneut auf, wenn der Child-Tab noch generiert.

Aktionsziele akzeptieren entweder einen CSS-Selektor oder exakten sichtbaren Text / aria-label / Platzhalter / Namen / zugeordneten Labeltext. Mehrdeutige Ziele schlagen fehl, anstatt zu raten.

Die Brücke bietet keinen Zugriff auf Cookies, lokalen Speicher, Sitzungsspeicher, gespeicherte Passwörter, versteckte Eingabewerte, beliebige JavaScript-Ausführung, Chrome-interne Seiten oder Inkognito-Tabs. Sie verwendet die Chrome-Debugger-API nicht.

Bewährter Weg

Der End-to-End-Test startet einen echten Chromium-Prozess mit der entpackten Manifest-V3-Erweiterung, startet den echten Native-Messaging-Host, verbindet einen MCP-Client über Streamable HTTP, öffnet Live-Seiten, listet und liest sie und verifiziert, dass ein Passwort-Eingabewert nicht zurückgegeben wird. Die Unit-/Integrationstests validieren Seitenaktionen, MCP-Routing, die Registrierung/Komposition der ChatGPT-Child-Agenten-Werkzeuge, die Synchronisierung der generierten Erweiterungsversion sowie die Tatsache, dass die von Chrome/Native Messaging verwendeten Laufzeitdateien von Git nachverfolgt werden.

MCP client
  -> http://127.0.0.1:2091/mcp
  -> native host process
  -> Chrome Native Messaging
  -> MV3 extension
  -> live Chrome tabs

Führe jedes Gate aus:

npm ci
npm run check

Related MCP server: sansan-chrome-mcp

Architektur

ChatGPT developer-mode app
          |
          | OpenAI Secure MCP Tunnel (outbound HTTPS)
          v
127.0.0.1:2091/mcp
          |
          | same local Node process
          v
Chrome Native Messaging host
          |
          v
Chrome MV3 extension
          |
          +-- chrome.tabs
          +-- chrome.scripting (isolated-world reads + actions)

Chrome startet den nativen Host, wenn die Erweiterung eine Verbindung herstellt. Der native Host startet den Loopback-MCP-Endpunkt. Deshalb muss Chrome geöffnet und die Erweiterung aktiviert sein, wann immer ChatGPT die App verwendet.

Voraussetzungen

• macOS

• Google Chrome 120+

• Node.js 20+

• Ein ChatGPT-Konto, für das der Entwicklermodus verfügbar ist

• Eine OpenAI-Platform-Tunnel-ID und ein Runtime-API-Schlüssel mit Tunnels Read + Use

• tunnel-client

1. Den nativen Host installieren und die Erweiterung einmal laden

npm run install:mac

Dies installiert das Native-Host-Manifest unter:

~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.komaksym.chrome_browser_mcp.json

Dann:

1. Öffne chrome://extensions.

2. Aktiviere den Entwicklermodus.

3. Klicke auf Entpackte Erweiterung laden.

4. Wähle das Verzeichnis dist/extension dieses Repositorys.

5. Bestätige, dass die Erweiterungs-ID genau Folgendes ist:

jlpddlfiallighiohmhhkemgbhofpnha

Fahre nicht fort, wenn die ID abweicht. Der native Host akzeptiert nur genau diesen Erweiterungs-Ursprung.

2. Zukünftige Patches aktualisieren

Du wählst das Erweiterungsverzeichnis nur einmal aus. Die gebaute Erweiterung und die MCP-Brücke unter dist/ sind in Git eingecheckt, und CI lehnt Quellcodeänderungen ab, deren eingecheckter Runtime-Build veraltet ist.

Für jeden späteren Patch ist der normale Aktualisierungsablauf genau:

git pull

Öffne dann chrome://extensions und klicke auf Aktualisieren. Wähle den Erweiterungspfad nicht erneut aus und führe keinen separaten Build-Befehl aus, nur um einen veröffentlichten Patch zu übernehmen.

git pull aktualisiert sowohl dist/extension (das, was Chrome lädt) als auch dist/bridge (das, was der native Host ausführt). Ein Klick auf Aktualisieren lädt die Verbindung zwischen der entpackten Erweiterung und Native Messaging neu, sodass die neu gezogene Laufzeit verwendet wird.

Die sichtbare Erweiterungsversion muss sich bei jedem Patch ändern. Für diesen Patch muss sie 0.1.2 anzeigen. Wenn sie weiterhin eine ältere Version anzeigt, wurde die gezogene Laufzeit nicht übernommen.

3. Die lokale Browser-Kette überprüfen

Halte Chrome geöffnet und führe dann aus:

npm run verify:local

Eine erfolgreiche Prüfung gibt Folgendes aus:

• die Erweiterungs-ID;

• die Erweiterungsversion;

• die MCP-Serverversion;

• die 17 angekündigten MCP-Werkzeuge.

Der Verifizierer schlägt fehl, wenn sich die Erweiterungs- und MCP-Version unterscheiden oder wenn die Brücke so alt ist, dass sie ihre MCP-Version nicht meldet. Dadurch ist eine veraltete Brücke mit 15 Werkzeugen sofort von einer veralteten Chrome-Erweiterung unterscheidbar.

4. Sicheren MCP-Tunnel konfigurieren

Erstelle in OpenAI Platform einen Tunnel und einen Runtime-API-Schlüssel. Dann:

export CONTROL_PLANE_API_KEY="sk-..."
./scripts/configure-tunnel.sh tunnel_0123456789abcdef0123456789abcdef

tunnel-client doctor --profile chrome-browser-mcp --explain
tunnel-client run --profile chrome-browser-mcp

Das Profil leitet den Tunnel weiter an:

http://127.0.0.1:2091/mcp

Halte tunnel-client run aktiv, wann immer ChatGPT die Browser-Werkzeuge benötigt.

5. Zu ChatGPT hinzufügen

1. Aktiviere in ChatGPT Einstellungen -> Sicherheit und Anmeldung -> Entwicklermodus.

2. Öffne Einstellungen -> Plugins.

3. Klicke auf +, um eine Entwicklermodus-App zu erstellen.

4. Wähle Tunnel als Verbindungstyp.

5. Wähle die Tunnel-ID aus oder füge sie ein.

6. Verwende die Metadaten aus app-metadata.json.

7. Bestätige, dass ChatGPT alle 17 Werkzeuge findet.

8. Klicke in einem neuen Chat auf + -> Mehr, wähle Chrome Browser und frage dann: List my open Chrome tabs.

Für die genaue Verifizierung und Fehlerbehebung siehe docs/CHATGPT_SETUP.md.

Sicherheitsmodell

Webseitentext ist Daten, niemals Autorität. Jedes Inhaltsergebnis enthält eine explizite Markierung für nicht vertrauenswürdigen Inhalt, und die Werkzeug-Anweisungen sagen dem Modell, Anweisungen, die es in Seiten findet, niemals in Aktionen umzusetzen.

Die Erweiterung fordert absichtlich Zugriff auf alle HTTP- und HTTPS-Seiten an, damit sie normale offene Tabs lesen und mit ihnen interagieren kann. Die Schutzgrenze ist:

• die Erweiterung wird lokal von dir geladen;

• Chrome startet nur den exakt auf der Whitelist stehenden nativen Host;

• der native Host lehnt jeden Ursprung außer der stabilen Erweiterungs-ID ab;

• der MCP-Endpunkt bindet nur an 127.0.0.1;

• der Tunnel ist ausschließlich ausgehend;

• Aktionen sind auf normale HTTP(S)-Tabs beschränkt und legen weder beliebiges JavaScript, Debugger-Zugriff, Cookies noch Browser-Speicher offen;

• Mehrdeutige, für Menschen lesbare Ziele werden abgelehnt, anstatt geraten zu werden.

Lies THREAT_MODEL.md und SECURITY_REVIEW.md, bevor du die Lösung unbeaufsichtigt einsetzt.

Bekannte Einschränkungen

• Es sollte immer nur ein Chrome-Profil die Erweiterung laden; zwei Profile können um Port 2091 konkurrieren.

• Chrome-interne Seiten, Seiten des Chrome Web Store, file://-Seiten und Inkognito-Tabs können nicht gelesen oder gesteuert werden.

• Cross-Origin-Iframes werden nicht durchlaufen.

• Ausschließlich auf Canvas basierende Anwendungen und der integrierte PDF-Viewer von Chrome liefern unter Umständen nur wenig semantischen Text.

• Der Extraktor gibt den sichtbaren Text, die Überschriften, Links und die Beschreibung des primären Dokuments zurück, nicht das rohe HTML. URL-Anmeldedaten und Fragmente werden entfernt, und sensible Abfrageparameter werden geschwärzt.

• press_key verwendet DOM-Tastaturereignisse; Enter und Escape erhalten ein explizites Standardverhalten, aber einige Websites erfordern vertrauenswürdige OS-/CDP-Tastatureingaben.

• Die Übermittlung von ChatGPT-Child-Agenten hängt vom aktuellen Web-Composer von ChatGPT (#prompt-textarea) und dem Markup des Senden-Buttons ab; eine zukünftige Änderung der ChatGPT-Benutzeroberfläche kann eine Aktualisierung dieser Selektoren erfordern.

• read_chatgpt_agent gibt den sichtbaren semantischen Seitentext des Child-Tabs zurück, keine privilegierte ChatGPT-API-Antwort.

• Der Datei-Upload ist bewusst nicht implementiert, weil eine allgemeine Umsetzung eine leistungsfähigere Dateisystem-/Debugger-Oberfläche erfordern würde.

Entwicklung

npm ci
npm run version:check
npm run typecheck
npm run lint
npm test
npm run artifacts:check
npm run test:e2e
npm audit