pw-pool

每个代理会话一个浏览器，用于 Playwright MCP。

@playwright/mcp 假定一个服务器对应一个浏览器。如果你在一台机器上运行两个代理会话，它们要么因配置文件锁而失败，要么（使用共享浏览器时）在同一个标签页空间中工作并互相导航页面。pw-pool 为每个会话提供独立的 Chrome，并记住哪个浏览器属于哪个会话。

配置文件

Chrome 将"用户"的所有信息保存在配置文件目录中（--user-data-dir）：Cookie、本地存储、已保存的密码、打开的标签页。这就是让你在多次运行之间保持登录状态的原因。同一时间只能有一个 Chrome 使用一个配置文件。pw-pool 为每个会话创建一个配置文件，在运行之间保留它，并且可以从模板中为新配置文件播种——模板是您已登录配置文件的登录文件的副本——这样新会话启动时就已经登录，而无需与任何人共享浏览器。

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。

然后使用 pw-mcp 作为 Playwright 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 服务器每个会话启动一次，因此已经打开的会话会保留其旧服务器和浏览器，直到重新启动。在更改后启动（或重新启动，例如 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 替代 npx @playwright/mcp 作为 MCP 服务器命令。它会找出是哪个会话在调用，从池中取出该会话的浏览器（如果需要则启动一个），并通过 CDP 对其运行捆绑的 @playwright/mcp。Stdio 直接透传。

• 当 MCP 退出时，浏览器保持运行。恢复的会话会获得相同的浏览器，包括标签页等所有内容。

• 没有打开的标签页且没有活动会话的浏览器会立即停止；仍有标签页的浏览器会在其会话结束后 1 小时停止（标签页已保存）。稍后启动会在同一配置文件上重新启动它并重新打开标签页。未使用的配置文件会在 30 天后删除。活动会话持有租约，永远不会被回收。

• 不会有任何窗口弹出：浏览器以无窗口方式启动，标签页在后台打开。捆绑的 MCP 为此携带了一个两行补丁（请参阅焦点）。

没有守护进程。状态是 ~/.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；对于会话很少的机器，请从 cron 或 launchd 运行 pw-pool gc。

配置位于 ~/.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 仍为每个实例显示一个图标；这会为窗口本身着色）。固定的 "R,G,B" 将所有池浏览器着色为相同颜色。

焦点

在 macOS 上，有两件事会激活 Chrome 应用并抢占用户焦点：启动时创建的窗口，以及在前台创建的标签页。pw-pool 使用 --no-startup-window 启动 Chrome，并使用 CDP 的 background: true 打开标签页。@playwright/mcp 没有此选项，因此 scripts/patch-focus.js 会更改捆绑副本中的两行（browser_tabs new → 后台标签页，browser_tabs select → 无 bringToFront）。该补丁在 npm install 时应用；pw-pool doctor 验证它；PW_MCP_FOREGROUND_TABS=1 恢复原始行为。

有一种情况超出了补丁的范围：当页面本身打开弹出窗口时（window.open 或点击时的 target="_blank" 链接），macOS 会激活浏览器来显示它，这与任何 Chrome 一样。浏览器默认有头，与 @playwright/mcp 一致。如果在共享机器上焦点窃取很重要，请以无头模式运行：pw-pool config set headless true、PW_POOL_HEADLESS=1，或按会话 pw-mcp --headless（以及 --headed 以在默认为无头时强制有头）。无头模式在快照和屏幕截图方面渲染相同。

故障排除

• MCP 在 browser_evaluate 后立即断开连接（"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 上进行一次性设置：包的设置 → 可信发布者 → 此仓库的 publish.yml 工作流。之后，通过打标签发布：npm version patch && git push --follow-tags。工作流运行测试和 npm publish --provenance。（首次发布（在包存在之前）在本地使用 npm publish --access public --auth-type=web 执行一次。）

许可证

MIT