Browser MCP

Machen Sie Ihren Chrome/Edge-Browser als MCP-Tools für jeden KI-Agenten verfügbar. Eine Chrome-Erweiterung (Manifest V3) fungiert selbst als MCP-Server: Sie verbindet sich mit einem code-mcp-gateway und beantwortet MCP-Anfragen direkt – kein lokaler Server erforderlich. Sie spricht dasselbe JSON-RPC-Protokoll wie code-mcp und fügt sich so in bestehende Agent-Setups ein.

So funktioniert es

flowchart LR
  subgraph Agent["Agent side"]
    A["MCP client / AI agent"]
  end

  subgraph Gateway["code-mcp-gateway (Cloudflare Worker)"]
    G["wss://code-mcp.tuanm.dev/ws/<id>"]
  end

  subgraph Browser["Your browser"]
    E["Extension (MV3)<br/>service worker = MCP server<br/>offscreen = WS bridge"]
    P["Page (content script)"]
  end

  A -- "MCP JSON-RPC" --> G
  G -- "register / keepalive /<br/>forward requests" --> E
  E -- "CDP / tabs / scripting" --> P

Das Popup nimmt eine Geräte-ID und einen Token entgegen; die Erweiterung verbindet sich direkt mit dem Gateway (Registrierung, Keepalive alle 25s, 75s Watchdog, Reconnect mit Jitter-Backoff) und bedient initialize / tools/list / tools/call direkt. Jeder Agent, der das Gateway erreichen kann, kann den Browser steuern.

Ein optionaler lokaler Server (browser-mcp.ts) fügt einen Dateispeicher (file_read, große Downloads/Uploads) und einen einfachen lokalen MCP-HTTP-Endpunkt hinzu. Siehe Lokaler Server.

Schnellstart

Chrome oder Edge >= 111. Bun >= 1.1 wird nur für den lokalen Server oder die Entwicklungswerkzeuge benötigt – die Erweiterung funktioniert eigenständig.

1. Erweiterung laden. Öffnen Sie chrome://extensions, aktivieren Sie den Entwicklermodus, klicken Sie auf Entpackte Erweiterung laden und wählen Sie packages/browser-extension. (Oder führen Sie bun browser-mcp.ts aus und laden Sie die ZIP-Datei von http://127.0.0.1:7777/extension herunter.)

2. Verbinden. Klicken Sie auf das Symbol in der Symbolleiste (das MCP-Zeichen wird grün, wenn eine Verbindung besteht). Geben Sie die Geräte-ID und den Token des Gateways ein und klicken Sie auf Verbinden. Das Popup zeigt Verbunden (Gateway).

3. Verwenden. Richten Sie einen beliebigen MCP-Client auf Ihr Gateway-Gerät. Die Erweiterung beantwortet tools/list mit 47 Tools.

Der Token muss mit dem auf dem Gateway für dieses Gerät konfigurierten übereinstimmen. Das Gateway leitet ihn bei jeder Anfrage weiter und die Erweiterung überprüft ihn. Lassen Sie ihn leer, und jeder, der das Gateway erreicht, kann den Browser steuern.

Lokaler Server

Nur für den Dateispeicher (file_read, Downloads/Uploads > 512 KB) oder einen lokalen MCP-HTTP-Endpunkt erforderlich:

bun browser-mcp.ts                  # http://127.0.0.1:7777/mcp
bun browser-mcp.ts --token <s>      # require auth on /mcp + /files

Wenn der Server läuft, übergibt das Popup die ID + den Token auch an den eigenen Gateway-Link des Servers; ohne ihn funktioniert die Erweiterung weiterhin direkt. Lokale Clients verwenden http://127.0.0.1:7777/mcp – siehe mcp-client.example.json (fügen Sie "headers": { "Authorization": "Bearer <token>" } hinzu, wenn Sie mit --token ausführen). Überprüfen: curl -s http://127.0.0.1:7777/health.

Remote-Zugriff über code-mcp-gateway

• Direkt (Standard). ID + Token im Popup eingeben; die Erweiterung stellt MCP selbst bereit. Kein lokaler Server.

• Serverseitige Verbindung. Mit dem lokalen Server verbindet sich das Popup mit wss://code-mcp.tuanm.dev/ws/<id> und der Server beantwortet MCP über HTTP.

• CLI (benutzerdefiniertes Gateway):

bun browser-mcp.ts --gateway <domain> --token <s> --id <device-id>

Gleiches Protokoll wie im Direktmodus. Verwenden Sie denselben --token auf dem Gateway-Gerät; führen Sie den Gateway-Modus niemals ohne einen aus. Setzen Sie BMCP_GATEWAY_DOMAIN, um den Standard-Gateway-Host des Popups zu überschreiben.

Tools (47)

Elementerkennung mit dem @ref-System: snapshot gibt einen interaktiven Elementbaum mit [ref=eN]-Markierungen zurück; jedes Interaktionswerkzeug akzeptiert den ref oder einen CSS-Selektor (refs werden gecacht und automatisch aufgelöst; veraltete refs ergeben den Fehler „run snapshot again“).

• Erkennung — snapshot, find (role/name/text/label/placeholder/ title/testid/selector), get, is

• Interaktion — click, dblclick, type, fill, check, uncheck, select, hover, focus, press, drag, scroll, upload

• Navigation — navigate, reload, back, forward, close, tabs, window

• Seiten auslesen — extract, execute, screenshot (image block), pdf, wait, highlight

• Status & Debugging — store, cookies, storage, console, errors, network, status, file_read

• Emulation & Steuerung — emulate, set (viewport/device/geo/offline/ headers/media), perms, auth, dialog, frames, touch, download

Die Erfassung von Konsole/Fehlern/Netzwerk startet beim ersten Aufruf (lazy). Laden Sie also nach dem Aktivieren neu oder navigieren Sie, um Datenverkehr zu erfassen. Back/forward verwenden den CDP-Navigationsverlauf. Führen Sie curl -s -X POST http://127.0.0.1:7777/mcp -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' für die vollständigen Schemas aus.

Flags

Sicherheit

• Origin-beschränkt. /browser/ws akzeptiert nur chrome-extension://-Origins; /mcp und /files/* lehnen Browser-Origins außer localhost ab – eine bösartige Website kann Ihren Browser nicht über localhost steuern (CSRF). Native MCP-Clients (ohne Origin-Header) sind nicht betroffen.

• --token schützt /mcp und /files/* (?token= oder Bearer); --extension-token fügt ein Geheimnis hinzu, das die Erweiterung auf der Bridge vorweisen muss.

• Datei-IDs sind 12-stellige zufällige Hexadezimalwerte, die gegen ein strenges Muster validiert werden; hochgeladene Dateinamen werden bereinigt. Größenbegrenzungen: Uploads 500 MiB, Screenshots 8 MiB inline.

• chrome.debugger zeigt die gelbe Infoleiste, solange es angehängt ist (Zustimmungssignal); perms/cookies verwenden wo möglich Nicht-Debugger-APIs.

• Bindet standardmäßig an 127.0.0.1; das Binden an 0.0.0.0 ohne --token gibt eine Warnung aus.

Timeouts

Bridge-Befehle: 30s Standard, 60s für navigate/execute/wait_for, 120s für download/file_upload – begrenzt auf 120s lokal und 55s im Gateway-Modus (das Gateway bricht Weiterleitungen nach 60s ab). Tools akzeptieren bridge_timeout zum Überschreiben.

Entwicklung

bun run check   # syntax-check server + scripts + extension JS
bun run test    # mock-extension + mock-gateway E2E suite
bun run build   # rebuild dist/browser-extension.zip
bun browser-mcp.ts  # run the server