browser-pool-mcp

A dynamic browser pool MCP server that wraps @playwright/mcp to enable multiple concurrent browser sessions for Claude Code and other MCP clients.

Problem Solved

The standard Playwright MCP server only allows one browser instance at a time. If you try to use browser tools from multiple Claude Code sessions simultaneously, you get:

Browser is already in use for C:\Users\...\mcp-chrome-xxx, use --isolated to run multiple instances

browser-pool-mcp solves this by:

• Spawning Playwright MCP instances on-demand on dynamic ports (9000+)
• Automatically detecting port conflicts from other sessions
• Assigning each Claude session to its own isolated browser
• Auto-cleanup of idle instances after 30 minutes

Architecture

Claude Code Session 1 ──stdio──> browser-pool-mcp ──SSE──> Playwright MCP (port 9000)
Claude Code Session 2 ──stdio──> browser-pool-mcp ──SSE──> Playwright MCP (port 9001)
Claude Code Session 3 ──stdio──> browser-pool-mcp ──SSE──> Playwright MCP (port 9002)

Each Claude Code session gets its own browser-pool-mcp process, which spawns and connects to an isolated Playwright instance on an available port.

Installation

Prerequisites

• Node.js 18+
• npm

Setup

1. Clone or download this repository:

git clone https://github.com/everdijsje/browser-pool-mcp.git
cd browser-pool-mcp
npm install

2. Add to your Claude Code MCP configuration (~/.claude.json):

{
  "mcpServers": {
    "browser": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/browser-pool-mcp/index.js"]
    }
  }
}

3. Restart Claude Code

Usage

Use browser tools as normal in Claude Code:

Navigate to https://example.com
Take a screenshot
Click on the "Learn more" link

Additional Tools

• pool_status - Check the status of running browser instances
• pool_test - Debug tool to test async responses

Configuration

Environment variables:

Variable	Default	Description
BROWSER_POOL_DEBUG	0	Set to 1 to enable debug logging to debug.log

Constants in index.js:

Constant	Default	Description
BASE_PORT	9000	Starting port for Playwright instances
MAX_INSTANCES	10	Maximum concurrent browser instances
INSTANCE_TIMEOUT_MS	1800000	Idle timeout before killing instance (30 min)

How It Works

1. When you call any browser tool (e.g., browser_navigate), browser-pool-mcp:

   • Checks if this session already has an assigned Playwright instance
   • If not, finds an available port (checking for conflicts)
   • Spawns npx @playwright/mcp@latest --port PORT --isolated
   • Connects via MCP SDK client over SSE
   • Proxies the tool call to Playwright

2. Each session is assigned one browser instance for its lifetime

3. Instances are cleaned up after 30 minutes of inactivity

4. When max instances are reached, the oldest idle instance is recycled

Supported Browser Tools

All standard Playwright MCP tools are proxied:

• browser_navigate - Navigate to URL
• browser_snapshot - Get page accessibility snapshot
• browser_click - Click element
• browser_type - Type text into element
• browser_screenshot - Take screenshot
• browser_tabs - Manage browser tabs
• browser_press_key - Press keyboard key
• browser_hover - Hover over element
• browser_select_option - Select dropdown option
• browser_evaluate - Run JavaScript
• browser_wait_for - Wait for condition
• browser_resize - Resize browser window
• browser_handle_dialog - Handle alerts/confirms
• browser_file_upload - Upload files
• browser_console_messages - Get console logs
• browser_network_requests - Get network activity
• browser_navigate_back - Go back
• browser_close - Close browser

Dependencies

• @modelcontextprotocol/sdk - MCP SDK for server and client communication
• zod - Schema validation
• @playwright/mcp - Spawned as child processes (installed via npx)

License

MIT

Author

Built by Claude Code for Everdijs