pw-pool

Ein Browser pro Agent-Sitzung für den Playwright MCP.

@playwright/mcp geht von einem Server und einem Browser aus. Wenn du zwei Agent-Sitzungen auf einer Maschine ausführst und sie entweder an der Profilsperre scheitern oder, bei einem gemeinsamen Browser, im selben Tab-Bereich arbeiten und sich gegenseitig durch die Seiten navigieren. pw-pool gibt jeder Sitzung ihr eigenes Chrome und merkt sich, wem welches gehört.

Profile

Chrome speichert alles über eine „Person“ in einem Profil-Verzeichnis (--user-data-dir): Cookies, lokalen Speicher, gespeicherte Passwörter, offene Tabs. Das hält dich zwischen den Läufen angemeldet. Nur ein Chrome kann ein Profil gleichzeitig verwenden. pw-pool erstellt ein Profil pro Sitzung, behält es zwischen den Läufen und kann ein neues aus einer Vorlage befüllen – einer Kopie der Anmeldedateien eines Profils, mit dem du bereits angemeldet bist –, sodass eine neue Sitzung angemeldet startet, ohne einen Browser mit jemandem zu teilen.

Related MCP server: playwright-mcp-supercharged

Install

Benötigt Node 22+ und macOS oder Linux.

git clone https://github.com/ckarnell/pw-pool && cd pw-pool
npm install            # pins @playwright/mcp and patches it
node bin/pw-pool.js install    # checks the setup; offers to download Chrome for Testing if missing

Oder global, was pw-mcp und pw-pool auf deinen PATH setzt: npm install -g github:ckarnell/pw-pool.

Dann verwende pw-mcp als Playwright-MCP-Befehl. Claude Code (~/.claude.json oder ein Projekt-.mcp.json):

"playwright": { "type": "stdio", "command": "pw-mcp" }

(oder "command": "node", "args": ["/path/to/pw-pool/bin/pw-mcp.js"] für ein Klon, das nicht auf dem PATH ist).

Andere MCP-Flags (--caps, --output-dir, …) können zu args hinzugefügt werden; sie werden durchgereicht. --headless wird auf den Start des Pools angewendet. --cdp-endpoint, --user-data-dir, --isolated und --browser werden mit einer Warnung verworfen, weil der Pool den Browser wählt.

Standardmäßig sind die Browser Playwrights Chrome for Testing. Um das bereits auf der Maschine installierte Chrome zu verwenden: pw-pool config set channel '"chrome"' (auch chrome-beta, chrome-canary, msedge), oder config.chrome für einen expliziten Pfad.

Optional, um jede Sitzung angemeldet zu starten:

pw-pool template save main --from ~/path/to/a/signed-in/user-data-dir
pw-pool config set defaultTemplate '"main"'

Wechseln bei geöffneten Sitzungen

Du kannst die MCP-Konfiguration jederzeit ändern; nichts Laufendes wird beeinflusst. Ein MCP-Server wird einmal pro Sitzung gestartet, sodass bereits geöffnete Sitzungen ihren alten Server und Browser behalten, bis sie neu gestartet werden. Sitzungen, die nach der Änderung starten (oder neu starten, z. B. claude --resume), verwenden pw-pool. Reihenfolge, die funktioniert:

1. Speichere eine Vorlage aus dem Browser, den du heute verwendest, und setze sie als Standard (oben), damit die neuen Browser angemeldet sind.

2. Ändere den MCP-Eintrag auf pw-mcp.

3. Sonst nichts. Alte Sitzungen laufen weiter; neue bekommen ihren eigenen Browser.

Um zurückzugehen, stelle den alten MCP-Eintrag wieder her. Browser, die pw-pool gestartet hat, werden nach der Leerlauf-TTL beendet, oder sofort mit pw-pool stop all. Ein Browser, den du zuvor ausgeführt hast (z. B. ein gemeinsamer auf einem festen CDP-Port), wird von pw-pool nicht berührt und kann daneben weiterlaufen.

So funktioniert es

session A ─▶ pw-mcp ─▶ registry ─▶ Chrome :9300, profiles/A/ ◀─ @playwright/mcp --cdp-endpoint
session B ─▶ pw-mcp ─▶ registry ─▶ Chrome :9301, profiles/B/ ◀─ @playwright/mcp --cdp-endpoint

• pw-mcp ersetzt npx @playwright/mcp als MCP-Serverbefehl. Es findet heraus, welche Sitzung aufruft, nimmt den Browser dieser Sitzung aus dem Pool (startet einen, falls nötig) und führt das gebündelte @playwright/mcp über CDP dagegen aus. Stdio geht direkt durch.

• Wenn der MCP beendet wird, bleibt der Browser aktiv. Eine fortgesetzte Sitzung bekommt denselben Browser, Tabs und alles.

• Ein Browser ohne offene Tabs und ohne aktive Sitzung wird sofort gestoppt; einer, der noch Tabs hat, wird 1 Stunde nach Ende seiner Sitzung gestoppt (Tabs gespeichert). Ein späterer Start startet ihn auf demselben Profil neu und öffnet die Tabs wieder. Ungenutzte Profile werden nach 30 Tagen gelöscht. Eine aktive Sitzung hält einen Lease und wird nie beendet.

• Nichts öffnet ein Fenster: Browser starten ohne Fenster, und Tabs werden im Hintergrund geöffnet. Der gebündelte MCP trägt einen Zwei-Zeilen-Patch aus demselben Grund (siehe Fokus).

Kein Daemon. Der Zustand ist ein JSON-Register unter ~/.pw-pool/, geschützt durch eine Sperre.

Welche Sitzung welche ist

pw-mcp benötigt einen stabilen Schlüssel pro Sitzung. In Reihenfolge:

1. --key / PW_POOL_KEY — explizit. Jede Umgebung kann das setzen. PW_POOL_NAME beschriftet das Fenster.

2. CLAUDE_CODE_SESSION_ID — Claude Code (2.1.239+) setzt es in der Umgebung des MCP-Servers.

3. ~/.claude/sessions/<parent pid>.json — Claude Code schreibt dort seine Sitzungs-ID, Name und Arbeitsverzeichnis.

4. Die übergeordnete PID — Fallback; der Browser wird gelöscht, wenn der Lease endet.

Gleicher Schlüssel, gleicher Browser. claude --resume behält die Sitzungs-ID, also bekommt es seinen Browser zurück.

Vorlagen

pw-pool template save <name> --from <dir> kopiert die Anmeldedateien eines Profils (Cookies, lokalen Speicher, IndexedDB, gespeicherte Passwörter, Einstellungen — ein paar MB; keine Caches). Das Profil einer neuen Sitzung wird aus --template <name>, PW_POOL_TEMPLATE oder config.defaultTemplate befüllt, einmal, wenn es erstellt wird. Danach entwickelt sich jedes Profil eigenständig. --fresh erzwingt ein leeres Profil.

Vorlagen und Profile enthalten echte Anmeldedaten. Halte ~/.pw-pool/ aus Repositories heraus. Eine Vorlage ist eine Momentaufnahme: Speichere sie erneut, nachdem du dich bei etwas Neuem angemeldet hast.

CLI

pw-pool install [--yes]            first-time setup; asks before downloading Chrome
pw-pool ls                         registered browsers: key, name, port, pid, status, tabs, leases
pw-pool cdp [key] [--ensure]       CDP endpoint of a session's browser (default: the calling session)
pw-pool tabs [key]
pw-pool gc [--force] [--dry-run]   reap stale leases, idle browsers, old profiles
pw-pool stop <key|all> [--rm]      stop a browser (tabs saved); --rm also deletes its profile
pw-pool template save <name> [--from <dir>] | ls | rm <name>
pw-pool config [get <key> | set <key> <json>]
pw-pool doctor

<key> ist ein vollständiger Schlüssel, ein eindeutiges Präfix oder ein Sitzungsname. pw-pool cdp --ensure ermöglicht Skripten, denselben Browser wie die MCP-Sitzung zu steuern. Jeder pw-mcp-Start führt gc aus; für Maschinen, auf denen Sitzungen selten sind, führe pw-pool gc über cron oder launchd aus.

Die Konfiguration liegt in ~/.pw-pool/config.json (pw-pool config): portRange [9300, 9399], idleTtlHours 1, profileTtlDays 30, defaultTemplate, sourceProfile, chrome, channel, headless, sandbox (aus, wie Playwrights chromiumSandbox), profileTheme, windowCascade, windowSize, extraChromeArgs, launchTimeoutMs. PW_POOL_HOME verschiebt das gesamte Zustandsverzeichnis; PW_POOL_HEADLESS=1 führt Browser headless aus (Server, Container).

profileTheme: true färbt die Symbolleiste jedes Browsers in einer stabilen Farbe, die von seinem Schlüssel abgeleitet ist, sodass mehrere Pool-Fenster auf dem Bildschirm leicht zu unterscheiden sind (macOS Cmd-Tab zeigt weiterhin ein Symbol pro Instanz; dies färbt das Fenster selbst). Ein festes "R,G,B" thematisiert alle Pool-Browser gleich.

Fokus

Auf macOS aktivieren zwei Dinge eine Chrome-App und nehmen dem Benutzer den Fokus: ein beim Start erstelltes Fenster und ein im Vordergrund erstellter Tab. pw-pool startet Chrome mit --no-startup-window und öffnet Tabs mit CDPs background: true. @playwright/mcp hat dafür keine Option, daher ändert scripts/patch-focus.js zwei Zeilen in der gebündelten Kopie (browser_tabs new → Hintergrund-Tab, browser_tabs select → kein bringToFront). Der Patch wird bei npm install angewendet; pw-pool doctor überprüft ihn; PW_MCP_FOREGROUND_TABS=1 stellt das ursprüngliche Verhalten wieder her.

Ein Fall liegt außerhalb der Reichweite des Patches: Wenn eine Seite selbst ein Popup öffnet (window.open oder ein target="_blank"-Link bei einem Klick), aktiviert macOS den Browser, um es zu zeigen, genau wie bei jedem Chrome. Browser sind standardmäßig mit Fenster, passend zu @playwright/mcp. Wenn dieser Fokusraub auf einer gemeinsam genutzten Maschine wichtig ist, führe headless aus: pw-pool config set headless true, PW_POOL_HEADLESS=1, oder pro Sitzung pw-mcp --headless (und --headed, um headless zu erzwingen, wenn der Standard headless ist). Headless rendert identisch für Snapshots und Screenshots.

Fehlerbehebung

• Der MCP trennt die Verbindung („Connection closed“) direkt nach einem browser_evaluate. Das Ergebnis war größer als das Pro-Nachrichten-Limit des Clients (16 MB in Claude Code), also hat der Client die Verbindung geschlossen. Das ist nicht spezifisch für pw-pool. Der Client startet den Server innerhalb von Sekunden neu und pw-mcp verbindet sich wieder mit demselben Browser, einschließlich Tabs; rufe das Tool erneut auf und gib kleinere Werte zurück. Claude Code speichert das Serverprotokoll unter ~/Library/Caches/claude-cli-nodejs/<project>/mcp-logs-playwright/.

• „Chrome exited during startup“ oder „did not answer“: Der Fehler zitiert das Ende von ~/.pw-pool/logs/<key>.chrome.log. Häufige Ursachen: kein Display auf Linux (verwende headless oder Xvfb), eine Binärdatei, die nicht ausgeführt werden kann (pw-pool doctor).

• Ein Browser scheint niemandem zu gehören: pw-pool ls zeigt Leases; ! markiert einen Halter, der beendet wurde. pw-pool gc räumt diese auf; pw-pool stop <key> stoppt einen Browser, bei dem du dir sicher bist.

Entwicklung

npm test               # unit tests (no browser needed)
npm run test:e2e       # real browsers, throwaway pool home: isolation, reattach, concurrency, recovery, templates
npm run test:docker    # the same on Linux in a container

Die @playwright/mcp-Version ist festgepinnt. Um sie zu erhöhen, ändere die Version, führe npm install aus und repariere scripts/patch-focus.js, falls die Installation fehlschlägt (das Bundle hat seine Form geändert).

Veröffentlichung

Die Veröffentlichung verwendet npm Trusted Publishing (OIDC von GitHub Actions) — keine Tokens. Einmalige Einrichtung auf npmjs.com: Einstellungen des Pakets → Trusted Publisher → Workflow publish.yml dieses Repos. Danach veröffentliche per Tag: npm version patch && git push --follow-tags. Der Workflow führt die Tests aus und npm publish --provenance. (Die allererste Veröffentlichung, bevor das Paket existiert, wird einmal lokal mit npm publish --access public --auth-type=web durchgeführt.)

Lizenz

MIT