playwright-mcp-parallel

Drop-in parallel enhancement over @playwright/mcp
Run multiple isolated browser instances simultaneously, each with its own context, auth, and state.

---

Why playwright-mcp-parallel?

Standard @playwright/mcp supports only one browser instance per server. This package extends it to support N parallel instances, enabling:

• 🔀 Parallel task execution — Run multiple browser tasks at the same time
• 🔐 Auth cloning — Clone cookies/localStorage from your logged-in Chrome to all new instances
• 🧩 Isolated contexts — Each instance has fully independent state
• 🔌 Drop-in compatible — All original @playwright/mcp tools available via page_* prefix

---

Installation & Setup

Claude Desktop / Cursor / VS Code / Any MCP client

{
  "mcpServers": {
    "playwright-parallel": {
      "command": "npx",
      "args": [
        "playwright-mcp-parallel@latest"
      ]
    }
  }
}

With options (headless, etc.)

{
  "mcpServers": {
    "playwright-parallel": {
      "command": "npx",
      "args": [
        "playwright-mcp-parallel@latest",
        "--headless"
      ]
    }
  }
}

---

Tools Reference

🔌 Connection & Auth

Tool	Description
browser_connect	Connect to an existing Chrome via CDP and extract auth (cookies + localStorage). Chrome must be started with --remote-debugging-port=9222.
instance_export_auth	Export auth state from a specific instance (or the connected Chrome). Updates global auth so new instances will inherit it.

🖥️ Instance Management

Tool	Description
instance_create	Create a new isolated browser instance. Optionally auto-clone auth from connected Chrome.
instance_list	List all active instances with their current URLs and titles.
instance_close	Close a specific instance and release its resources.
instance_close_all	Close all instances at once.

🌐 Browser Tools (All Original @playwright/mcp tools)

All tools from @playwright/mcp are available with a page_ prefix and require an instanceId parameter:

Tool	Description
page_browser_navigate	Navigate an instance to a URL
page_browser_click	Click an element in an instance
page_browser_type	Type text into an element
page_browser_screenshot	Take a screenshot of an instance
page_browser_snapshot	Get accessibility snapshot of an instance
page_browser_evaluate	Execute JavaScript in an instance
page_browser_wait_for	Wait for a condition in an instance
...	All other @playwright/mcp tools with page_ prefix

---

Usage Examples

Typical Workflow: Auth Cloning + Parallel Tasks

1. Start Chrome with debugging:
   chrome.exe --remote-debugging-port=9222

2. Log in manually in Chrome

3. In your AI agent:
   → browser_connect()                          # Extract auth from Chrome
   → instance_create({ instanceId: "task-1", url: "https://app.example.com" })
   → instance_create({ instanceId: "task-2", url: "https://app.example.com" })
   → (Both instances are logged in automatically!)

4. Run tasks in parallel:
   → page_browser_click({ instanceId: "task-1", ... })
   → page_browser_click({ instanceId: "task-2", ... })

5. Export auth from a running instance (e.g., after login flow):
   → instance_export_auth({ instanceId: "task-1" })
   → instance_create({ instanceId: "task-3" })  # Also logged in

Export Auth from Instance

→ instance_create({ instanceId: "login-bot", url: "https://example.com/login" })
→ page_browser_click({ instanceId: "login-bot", ... })   # complete login
→ instance_export_auth({ instanceId: "login-bot" })      # export & set as global auth
→ instance_create({ instanceId: "worker-1" })            # inherits login state
→ instance_create({ instanceId: "worker-2" })            # inherits login state

---

CLI Options

All @playwright/mcp CLI options are supported:

npx playwright-mcp-parallel@latest [options]

Option	Description
--headless	Run browser in headless mode
--browser <browser>	Browser to use: chrome, firefox, webkit, msedge
--viewport-size <size>	Viewport size, e.g. 1280x720
--user-data-dir <path>	Path to user data directory
--storage-state <path>	Path to storage state JSON file
--proxy-server <proxy>	Proxy server, e.g. http://myproxy:3128
--no-sandbox	Disable sandbox
--port <port>	Port for SSE transport
--isolated	Keep browser profile in memory only

For the full list of options, see @playwright/mcp documentation.

---

How It Works

playwright-mcp-parallel
├── Management Layer
│   ├── browser_connect      → Extract auth from existing Chrome
│   ├── instance_create      → Launch isolated browser + clone auth
│   ├── instance_list        → List active instances
│   ├── instance_close       → Dispose instance
│   ├── instance_close_all   → Dispose all
│   └── instance_export_auth → Export cookies/localStorage from instance
│
└── Per-Instance Tool Dispatch
    └── page_* tools → routed to the correct BrowserBackend by instanceId

Each instance_create call launches a new Chromium process with an isolated context. Auth state (cookies + localStorage) extracted via browser_connect or instance_export_auth is automatically injected into new contexts.

---

Differences from @playwright/mcp

Feature	@playwright/mcp	playwright-mcp-parallel
Browser instances	1	Unlimited
Parallel execution	❌	✅
Auth cloning	❌	✅
Auth export	❌	✅
Original tools	✅	✅ (via page_ prefix)
Drop-in config	✅	✅

---

Requirements

• Node.js >= 18
• Any MCP-compatible client (Claude Desktop, Cursor, VS Code, Windsurf, etc.)

---

License

Apache-2.0 — based on @playwright/mcp by Microsoft.