chrome-devtools-mcp-mux

Nutzen Sie eine Chrome-Instanz für viele MCP-Clients. Jeder Client – zum Beispiel eine separate Claude Code-Sitzung – erhält seinen eigenen isolierten Satz an Tabs, während alle auf demselben Browser und Profil laufen.

Welches Problem wird gelöst

chrome-devtools-mcp stellt Chrome DevTools für einen MCP-Client bereit. Das funktioniert perfekt für einen Client, aber wenn sich zwei Clients gleichzeitig verbinden (zwei Claude Code-Fenster, ein Claude Code plus ein Gemini CLI usw.), kommen sie sich bei den Tabs in die Quere – list_pages zeigt alles an, select_page führt zu Race Conditions, new_page landet im falschen Fenster.

cdmcp-mux schaltet sich zwischen die Clients und chrome-devtools-mcp und gibt jeder Verbindung einen eigenen isolierten Tab-Satz, während nur ein einziges Chrome-Exemplar ausgeführt wird.

Installation und Konfiguration (einmalig)

git clone <this-repo> chrome-devtools-mcp-mux
cd chrome-devtools-mcp-mux
npm install
npm run build
npm link           # exposes `cdmcp-mux` on PATH

Dann in der .mcp.json jedes MCP-Clients:

{
  "mcpServers": {
    "chrome": { "command": "cdmcp-mux" }
  }
}

Das ist alles. Der erste Client, der eine Verbindung herstellt, startet automatisch einen gemeinsamen Daemon; nachfolgende Clients verbinden sich mit demselben Daemon.

Überprüfung der Funktionsweise

Starten Sie zwei MCP-Clients mit der oben genannten Konfiguration. Bitten Sie das Modell in jedem Client:

1. Eine andere URL über new_page zu öffnen.

2. list_pages auszuführen.

Jeder Client sollte nur seine eigene Seite sehen. Führen Sie auf dem Host cdmcp-mux status aus, um beide Kontexte nebeneinander im Daemon zu sehen.

Für eine vollständige Demo mit aufgezeichnetem Video siehe demo/.

Umgebungsvariablen (optional)

Debugging

Alles außerhalb des Bandes; der Mux macht Debug-Tools niemals für MCP-Clients zugänglich.

Das Protokoll befindet sich unter ~/.local/state/cdmcp-mux/mux.log.

Funktionsweise

flowchart TB
    subgraph clients["one process per MCP client"]
      direction LR
      C1["Claude Code #1"] -- "stdio (MCP)" --> S1["cdmcp-mux shim"]
      C2["Claude Code #2"] -- "stdio (MCP)" --> S2["cdmcp-mux shim"]
    end

    subgraph shared["shared — auto-spawned on first connect"]
      direction TB
      D["mux daemon<br/><i>per-connection context table</i><br/>(socket fd → ctxId → owned pageIds)"]
      U["chrome-devtools-mcp subprocess<br/><code>--experimentalPageIdRouting</code><br/><code>--userDataDir <fixed></code>"]
      B["Chromium<br/><i>one instance, one profile</i>"]
      D -- "stdio (MCP)<br/>rewrite + filter" --> U
      U -- "CDP" --> B
    end

    S1 -- "unix socket" --> D
    S2 -- "unix socket" --> D

    classDef client fill:#e3f2fd,stroke:#1976d2
    classDef shim fill:#fff3e0,stroke:#f57c00
    classDef core fill:#f3e5f5,stroke:#7b1fa2
    classDef browser fill:#e8f5e9,stroke:#388e3c
    class C1,C2 client
    class S1,S2 shim
    class D,U core
    class B browser

Jeder MCP-Client startet sein eigenes cdmcp-mux-Shim (so funktioniert .mcp.json – ein Kindprozess pro Client). Das Shim ist eine reine Byte-Pipe zwischen der Stdio des Clients und einem Unix-Socket; das erste Shim, das eine Verbindung herstellt, startet automatisch den gemeinsamen Daemon, spätere Shims verbinden sich damit. Der Daemon besitzt einen chrome-devtools-mcp-Subprozess, der ein Chromium mit einem --userDataDir steuert.

Jede Unix-Socket-Verbindung = ein frischer BrowserContext (isolierte Cookies, localStorage, WebSockets). Der Daemon bewirbt exakt dieselben Tool-Schemas wie das Standard-chrome-devtools-mcp – pageId und isolatedContext werden aus dem entfernt, was der Client sieht, und bei jedem tools/call aus der Eigentumstabelle des Daemons pro Verbindung wieder eingefügt. Die Atomarität nutzt das Upstream---experimentalPageIdRouting, sodass gleichzeitige Aufrufe aus verschiedenen Kontexten sich nicht gegenseitig stören können. Wenn ein Client die Verbindung trennt, werden seine Tabs geschlossen und sein Browser-Kontext zerstört.

Entwicklungshinweise

Dieses Projekt wurde von Anfang bis Ende von einem Claude-Code-Agenten in einer einzigen Arbeitssitzung geschrieben, gesteuert durch Live-Konversationsanforderungen. Der vollständige Testplan ist nach funktionaler Korrektheit gestaffelt (58 Tests, ~19 s, alle bestanden), und der Multiplexer wurde anschließend visuell über einen VNC-automatisierten Reproduzierer demonstriert.

Für die PRD-zu-Test-Zuordnung siehe DEMO.md. Für das vollständige agentische Entwicklungsprotokoll – Anforderungsermittlung, Architekturiteration, Teststaffelung und die drei Aufnahmen der Videodemo – siehe demo/README.md.

Testen

# requires a Chromium binary; the smoke/e2e tests need it
CDMCP_MUX_CHROMIUM=/usr/bin/chromium npm test

Erwartet: 8 Dateien, 58 Tests, alle bestanden.

Veröffentlichung

CI läuft bei jedem Push und PR gegen main unter Verwendung von Node 22 und 24, wobei gebaut, typgeprüft und die vollständige 58-Test-Suite ausgeführt wird (einschließlich der echten Chromium-Smoke- und Binary-E2E-Tests).

Die Veröffentlichung erfolgt automatisiert über .github/workflows/publish.yml, die bei der Veröffentlichung eines GitHub-Releases ausgeführt wird:

1. Erhöhen der version in package.json, Commit, Tag als v<version>.

2. gh release create v<version> --generate-notes.

3. Der Workflow baut, testet und führt npm publish mit npm provenance aus (signiert über GitHub OIDC, der Workflow hat id-token: write).

NPM_TOKEN ist das einzige erforderliche Repo-Secret. Das Paket wird mit publishConfig.provenance: true veröffentlicht, daher ist das --provenance-Flag implizit. Sobald dieses Repo als vertrauenswürdiger Herausgeber bei npmjs.com registriert ist, kann das NPM_TOKEN-Secret vollständig entfernt werden.

Lizenz

Apache-2.0 – siehe LICENSE. Identisch mit dem Upstream chrome-devtools-mcp.