pw-pool

Playwright MCP 向けに、エージェントセッションごとにブラウザを1つずつ用意します。

@playwright/mcp はサーバー1つとブラウザ1つを想定しています。1台のマシンで2つのエージェントセッションを実行すると、プロファイルのロックで失敗するか、ブラウザを共有した場合には同じタブ空間で動作し、お互いのページを移動してしまいます。pw-pool は セッションごとに専用の Chrome を持たせ、どれがどのセッションのものかを把握します。

プロファイル

Chrome は「ユーザー」に関するすべてを プロファイル ディレクトリ（--user-data-dir）に保存します。Cookie、ローカルストレージ、保存済みパスワード、開いているタブなどです。これによって、実行間でもログイン状態が維持されます。1つのプロファイルを同時に使える Chrome は1つだけです。pw-pool はセッションごとに1つのプロファイルを作成し、実行間で保持します。また、テンプレート（すでにログイン済みのプロファイルのログインファイルのコピー）から新しいプロファイルを生成できます。これにより、新しいセッションは誰ともブラウザを共有せずにログイン済みの状態で開始できます。

Related MCP server: antigravity-browser

インストール

Node 22+ と macOS または 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

またはグローバルにインストールすると、pw-mcp と pw-pool が PATH に入ります: npm install -g github:ckarnell/pw-pool。

そして、Playwright MCP コマンドとして pw-mcp を使います。Claude Code（~/.claude.json またはプロジェクトの .mcp.json）:

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

（PATH にないクローンの場合は、"command": "node", "args": ["/path/to/pw-pool/bin/pw-mcp.js"] を使います）。

他の MCP フラグ（--caps、--output-dir、…）は args に追加できます。そのまま渡されます。--headless はプールの起動に適用されます。--cdp-endpoint、--user-data-dir、--isolated、--browser は、プールがブラウザを選択するため、警告付きで削除されます。

デフォルトのブラウザは Playwright の Chrome for Testing です。マシンにインストール済みの Chrome を使うには: pw-pool config set channel '"chrome"'（chrome-beta、chrome-canary、msedge も可）。明示的なパスの場合は config.chrome です。

すべてのセッションをログイン済みで開始する場合（任意）:

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

セッションが開いている間の切り替え

MCP 設定はいつでも変更でき、実行中のものには影響しません。MCP サーバーはセッションごとに1回起動されるため、すでに開いているセッションは再起動するまで旧来のサーバーとブラウザを保持します。変更後に開始（または再開、たとえば claude --resume）したセッションは pw-pool を使用します。うまくいく順序は次のとおりです。

1. 現在使っているブラウザからテンプレートを保存し、それをデフォルト（上記）に設定します。これで新しいブラウザがログイン済みになります。

2. MCP エントリを pw-mcp に変更します。

3. 他には何もする必要はありません。古いセッションは継続し、新しいセッションにはそれぞれ専用のブラウザが与えられます。

元に戻すには、以前の MCP エントリを復元します。pw-pool が起動したブラウザはアイドル TTL 後に終了し、pw-pool stop all で即時に終了します。以前から動かしていたブラウザ（たとえば固定 CDP ポートで共有しているもの）は pw-pool の対象外で、そのまま並行して動作し続けることができます。

動作の仕組み

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 は MCP サーバーコマンドとして npx @playwright/mcp を置き換えます。呼び出しているセッションを特定し、そのセッションのブラウザをプールから取得（必要なら起動）し、バンドルされている @playwright/mcp を CDP 経由でそのブラウザに対して実行します。Stdio はそのまま通過します。

• MCP が終了してもブラウザは起動したままです。再開したセッションは同じブラウザ、タブも含めてそのまま取得します。

• 開いているタブがなく、アクティブなセッションもないブラウザはすぐに停止されます。まだタブがあるブラウザは、セッション終了から1時間後に停止されます（タブは保存されます）。その後起動すると、同じプロファイルで再起動され、タブが再度開きます。未使用のプロファイルは30日後に削除されます。アクティブなセッションはリースを保持しているため、回収されることはありません。

• ウィンドウを表示する操作はありません。ブラウザはウィンドウなしで起動し、タブはバックグラウンドで開かれます。バンドルされた MCP には同じ理由による2行のパッチがあります（Focus を参照）。

デーモンはありません。状態は ~/.pw-pool/ 配下の JSON レジストリで管理され、ロックによって保護されます。

どのセッションがどれか

pw-mcp にはセッションごとに安定したキーが必要です。優先順に:

1. --key / PW_POOL_KEY — 明示的な指定。任意の環境から設定できます。PW_POOL_NAME はウィンドウのラベルになります。

2. CLAUDE_CODE_SESSION_ID — Claude Code（2.1.239+）が MCP サーバーの環境変数に設定します。

3. ~/.claude/sessions/<parent pid>.json — Claude Code はセッション ID、名前、cwd をここに書き込みます。

4. 親 PID — フォールバック。リース終了時にブラウザは削除されます。

同じキーには同じブラウザが対応します。claude --resume はセッション ID を維持するので、再び同じブラウザを取得できます。

テンプレート

pw-pool template save <name> --from <dir> は、プロファイルのログインファイル（Cookie、ローカルストレージ、IndexedDB、保存済みパスワード、設定など数MB）をコピーします（キャッシュは含みません）。新しいセッションのプロファイルは、作成時に一度だけ --template <name>、PW_POOL_TEMPLATE、または config.defaultTemplate からシードされます。その後、各プロファイルは独立して変化します。--fresh は空のプロファイルを強制します。

テンプレートとプロファイルには実際の認証情報が含まれます。~/.pw-pool/ をリポジトリに入れないでください。テンプレートはある時点のコピーです。新しいサービスにサインインしたら、もう一度保存してください。

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> は、完全なキー、一意なプレフィックス、またはセッション名です。pw-pool cdp --ensure を使うと、スクリプトがセッションの MCP と同じブラウザを操作できます。pw-mcp は起動のたびに gc を実行します。セッションがまれなマシンでは、pw-pool gc を cron または launchd から実行してください。

設定は ~/.pw-pool/config.json（pw-pool config）にあります: portRange [9300, 9399]、idleTtlHours 1、profileTtlDays 30、defaultTemplate、sourceProfile、chrome、channel、headless、sandbox（Playwright の chromiumSandbox と同様、オフ）、profileTheme、windowCascade、windowSize、extraChromeArgs、launchTimeoutMs。PW_POOL_HOME は状態ディレクトリ全体を移動します。PW_POOL_HEADLESS=1 はブラウザをヘッドレスで実行します（サーバー、コンテナ）。

profileTheme: true は、各ブラウザのツールバーをそのキーから導出された安定した色で着色し、複数のプールウィンドウが見分けやすくなります（macOS の Cmd-Tab ではインスタンスごとに1つのアイコンが表示されますが、これが色付けするのはウィンドウ自体です）。固定の "R,G,B" を指定すると、すべてのプールブラウザが同じテーマになります。

フォーカス

macOS では、起動時に生成されたウィンドウとフォアグラウンドのタブ生成の2つが Chrome アプリをアクティベートし、マシンを使用している人のフォーカスを奪います。pw-pool は --no-startup-window で Chrome を起動し、CDP の background: true でタブを開きます。@playwright/mcp にはこれに相当するオプションがないため、scripts/patch-focus.js がバンドル内の2行を変更します（browser_tabs new → バックグラウンドタブ、browser_tabs select → bringToFront をなし）。パッチは npm install で適用されます。pw-pool doctor で検証できます。PW_MCP_FOREGROUND_TABS=1 は元の動作に戻します。

パッチの届かないケースが1つあります。ページ自体 がポップアップを開く場合（window.open またはクリック時の target="_blank" リンク）です。その場合、macOS は通常の Chrome と同じように、表示するためにブラウザをアクティベートします。ブラウザはデフォルトでヘッド付きであり、@playwright/mcp と同じです。共有マシンでフォーカスが奪われるのが問題なら、ヘッドレスで実行してください: pw-pool config set headless true、PW_POOL_HEADLESS=1、またはセッションごとに pw-mcp --headless（デフォルトがヘッドレスの場合は --headed でヘッド付きを強制）。ヘッドレスでもスナップショットとスクリーンショットの描画は同じです。

トラブルシューティング

• browser_evaluate の直後に MCP が切断される（"Connection closed"）。 結果がクライアントのメッセージ単位の上限（Claude Code では 16 MB）を超えたために、クライアントが接続を閉じました。これは pw-pool 特有のものではありません。クライアントは数秒以内にサーバーを再起動し、pw-mcp はタブを含めた同じブラウザに再アタッチします。ツールを呼び直して、より小さな値を返してください。Claude Code のサーバーログは ~/Library/Caches/claude-cli-nodejs/<project>/mcp-logs-playwright/ にあります。

• "Chrome exited during startup" や "did not answer" というエラーは、~/.pw-pool/logs/<key>.chrome.log の末尾を記録していきます。一般的な原因: Linux でディスプレイがない（headless または Xvfb を使う）、実行できないバイナリ（pw-pool doctor）。

• 誰のものでもないように見えるブラウザ: pw-pool ls にリースが表示されます。! は終了した保持者を表します。pw-pool gc でそれらをクリアし、確認できたブラウザは pw-pool stop <key> で停止します。

開発

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

@playwright/mcp のバージョンは固定されています。上げるには、バージョンを変更し、npm install を実行します。インストールが失敗した場合（バンドルの構造が変わった場合）は、scripts/patch-focus.js を修正してください。

リリース

公開には npm の トラステッドパブリッシング（GitHub Actions からの OIDC）を使用します。トークンは不要です。npmjs.com での一度だけのセットアップ: パッケージの Settings → Trusted Publisher → このリポジトリの publish.yml ワークフロー。その後、タグ付けしてリリースします: npm version patch && git push --follow-tags。ワークフローはテストと npm publish --provenance を実行します。（初回のみ、パッケージがまだ存在しないため、ローカルで npm publish --access public --auth-type=web を一度実行します。）

ライセンス

MIT