🖥️ Browser Pool MCP

Dynamic browser pool MCP server — every agent gets its own isolated browser.

English | 中文文档

A Model Context Protocol server that wraps Microsoft's @playwright/mcp and turns it into a dynamic browser pool: each unique caller gets its own isolated Chrome instance, so multiple Claude Code sessions, subagents, or any MCP clients can run browser automation concurrently without conflicts.

✨ Features

• 🧩 Per-agent isolation — each unique _agent_id gets its own browser. No more "Browser is already in use" errors when multiple agents hit the browser at once.

• 🚀 On-demand spawning — browsers are lazily started on first use (local CLI, ~1s), never pre-allocated.

• 🧹 Auto-cleanup — idle instances are killed after 30 min; orphaned instances from crashed wrappers are cleaned on startup.

• 🛡️ Never kills busy agents — when the pool is full, the wrapper evicts only idle instances; if all are busy it waits, so a running agent's browser is never yanked away.

• 🔁 Backward compatible — calling tools without _agent_id shares one "default" browser, preserving original single-session behavior.

• 🌐 Full Playwright toolset — all @playwright/mcp tools (navigate, click, type, screenshot, evaluate, tabs, network…), no feature loss.

Related MCP server: hanzi-browse

🧠 Architecture

Claude Code main session ──stdio──> playwright-pool-mcp (this server)
                                        │
                                        ├── agent "A" ──SSE──> @playwright/mcp :9000 ──> Chrome A
                                        ├── agent "B" ──SSE──> @playwright/mcp :9001 ──> Chrome B
                                        ├── agent "C" ──SSE──> @playwright/mcp :9002 ──> Chrome C
                                        └── "default" ──SSE──> @playwright/mcp :9003 ──> Chrome D

The wrapper does not control Chrome directly. It spawns @playwright/mcp instances on demand and proxies MCP tool calls to them, adding per-agent routing.

🚀 Quick Start

Prerequisites

• Node.js ≥ 18

• npm

Install

git clone <your-repo-url> playwright-pool-mcp
cd playwright-pool-mcp
npm install
# First-time Chromium download (if needed):
npx playwright install chromium

Configure Claude Code

User-level global config (~/.claude.json):

{
  "mcpServers": {
    "playwright-pool": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/playwright-pool-mcp/playwright-pool-script.js"],
      "env": {
        "BROWSER_POOL_BASE_PORT": "9000",
        "BROWSER_POOL_MAX_INSTANCES": "10",
        "BROWSER_POOL_GLOBAL_MAX": "12",
        "BROWSER_POOL_INSTANCE_TIMEOUT_MS": "1800000",
        "BROWSER_POOL_DEBUG": "0"
      }
    }
  }
}

Restart Claude Code. Tools appear as mcp__playwright-pool__*.

💡 Usage

Mode 1: Shared (backward compatible)

Omit _agent_id — all calls share one "default" browser:

mcp__playwright-pool__browser_navigate(url="https://example.com")
mcp__playwright-pool__browser_snapshot()

Mode 2: Isolated per agent (recommended)

Pass _agent_id — each unique value gets its own browser:

subagent A: mcp__playwright-pool__browser_navigate(url="https://news.ycombinator.com", _agent_id="agent-a")
subagent B: mcp__playwright-pool__browser_navigate(url="https://github.com/trending",   _agent_id="agent-b")
subagent C: mcp__playwright-pool__browser_navigate(url="https://www.baidu.com",         _agent_id="agent-c")

⚠️ Important: pass the same _agent_id across all calls from one agent to keep its browser state (cookies, login, navigation). Different agents use different values.

Subagent template

Create .claude/agents/web-worker.md:

---
name: web-worker
description: Run browser tasks (scraping / research / testing / automation)
tools: mcp__playwright-pool__*, Read, Bash
---

Use mcp__playwright-pool__* tools to operate the browser.

**Key rule: pass the `_agent_id` parameter on every browser tool call.**
The main conversation may dispatch multiple web-workers concurrently; different
workers must use different `_agent_id` values so each gets its own isolated browser.

Examples:
- mcp__playwright-pool__browser_navigate(url="...", _agent_id="worker-1")
- mcp__playwright-pool__browser_evaluate(function="...", _agent_id="worker-1")

Use the same `_agent_id` for all calls within one worker.

🛠️ Tools

All tools accept an optional _agent_id parameter. Aligned 1:1 with @playwright/mcp v0.0.78.

ℹ️ Element targeting: interaction tools use target (snapshot ref or CSS selector). The ref parameter is accepted as an alias for target (Claude Code's client maps it).

⚙️ Configuration

All config via environment variables in ~/.claude.json — no code changes needed:

Changes take effect after restarting Claude Code.

💡 Global limit (BROWSER_POOL_GLOBAL_MAX): each Claude Code window runs its own wrapper, and BROWSER_POOL_MAX_INSTANCES limits only that wrapper. To cap browser instances across ALL sessions (e.g. two windows must share a total of 12), set BROWSER_POOL_GLOBAL_MAX to the same value in every session's config. Slots are counted via a lock-protected counter file (~/.browser-pool/global-count) and are released when instances close or the wrapper exits gracefully.

🔍 How It Works

1. Any browser tool call arrives → wrapper extracts _agent_id (defaults to "default")

2. Looks up the per-agent assignment map → reuse existing browser if alive

3. If none: check the global limit (BROWSER_POOL_GLOBAL_MAX) → find a free port → spawn local @playwright/mcp CLI (node cli.js --port X --isolated)

4. Mark the instance busy during the call, so eviction never kills an in-flight call

5. Pool full? Evict only idle instances (oldest first); if all busy, wait up to 60s

6. Idle > 30 min → auto-killed; wrapper startup scans for orphaned instances and cleans them (PPID-guarded, never kills another live session's browsers)

7. Global slot accounting: acquired before spawn, released when the instance closes or the wrapper exits gracefully

📦 Dependencies

• @modelcontextprotocol/sdk — MCP protocol

• @playwright/mcp — browser automation engine

• zod — schema validation

📄 License

MIT