playwright-pool

Pools isolated Playwright MCP browser processes so multiple agents run concurrent browser sessions.

Updated Mar 6, 2026
One-click install
npx skills add https://github.com/timi-ty/agent-forge --skill playwright-pool-timi-ty
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: playwright-pool
Source: https://github.com/timi-ty/agent-forge/tree/main/skills/playwright-pool
Command: npx skills add https://github.com/timi-ty/agent-forge --skill playwright-pool-timi-ty

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires @playwright/mcp.

What problem does it solve? When multiple AI agents share a single Playwright MCP connection, every browser call hits the same browser instance, causing state contamination and blocking. This Skill installs and configures a pooling MCP proxy that gives each agent its own isolated browser session. ## Core Features & Use Cases - Session-based isolation: Agents acquire a session_id via browser_pool_acquire, pass it to every browser_* call, and release it with browser_pool_release when done. - Self-sizing pool: Keeps one warm standby browser for instant acquisition, grows on demand, and supports an optional maxConcurrent hard cap with queued acquires and configurable timeouts. - Guided setup wizard: Detects Cursor vs Claude Code, verifies Node.js and @playwright/mcp prerequisites, installs browser binaries, deploys the server, and registers it as an MCP server. - Use Case: Three agents scraping different sites in parallel each acquire their own session, navigate and snapshot independently, then release their browsers without interfering with one another. ## Quick Start Ask your agent to set up the playwright pool and follow the prompts to choose a browser, timeout, and concurrency cap.

Frequently Asked Questions about playwright-pool

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I run multiple Playwright browser sessions with AI agents?

Use a pooling MCP proxy that spawns isolated @playwright/mcp processes per agent. Each agent calls browser_pool_acquire to get a session_id, passes it to every browser_* tool call, and releases it with browser_pool_release when finished.

How do I set up the playwright-pool MCP server in Claude Code or Cursor?

Run the setup wizard, which verifies Node.js 18+ and @playwright/mcp, installs the chosen browser binary, deploys the server files, and registers the MCP server. Claude Code requires a window reload; Cursor requires a full restart.

Does the Playwright pool support limiting concurrent browsers?

Yes, set maxConcurrent in config.json to cap simultaneous browser processes. When the cap is reached, acquire calls queue and wait up to acquireTimeoutMs before returning a timeout error.

Why do I get a session_id is required error with browser tools?

Every browser_* call routed through the pool requires a session_id parameter. Call browser_pool_acquire first to obtain one, and re-acquire if the session was already released or never existed.

What happens if an agent forgets to release a browser session?

Unreleased sessions stay busy until the pool restarts, blocking that browser from other agents. Always call browser_pool_release even when an error occurs, and use browser_pool_status to inspect busy and queued counts.