playwright-mcp-orchestrator

playwright-mcp-orchestrator

Multi-agent orchestrator for Playwright MCP — multiple AI agents sharing one Chrome browser with tab isolation. Local-first, preserving your real browser state (cookies, logins, extensions, localStorage).

The Problem

The official @playwright/mcp only supports a single agent per browser. When multiple Claude Code agents (or any MCP clients) try to use it simultaneously, they fight over the same tabs and interfere with each other.

Existing workarounds all sacrifice something:

• --isolated mode gives each agent a fresh profile (no saved logins/cookies)
• Separate --user-data-dir per agent means separate profiles (no shared state)
• Community alternatives (ultimate-playwright-mcp, concurrent-browser-mcp) are unmaintained or don't share profiles

The Approach

Use a single Chrome instance with CDP (Chrome DevTools Protocol) as the shared backend, and orchestrate multiple @playwright/mcp sessions on top — each scoped to its own tabs.

┌─────────────────────────────────────────────┐
│              Chrome (one instance)           │
│         --remote-debugging-port=9222        │
│         --user-data-dir=<profile>           │
│                                             │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐       │
│  │ Agent 1 │ │ Agent 2 │ │ Agent 3 │ tabs  │
│  │  tabs   │ │  tabs   │ │  tabs   │       │
│  └────┬────┘ └────┬────┘ └────┬────┘       │
└───────┼──────────┼──────────┼───────────────┘
        │          │          │  CDP (ws://127.0.0.1:9222)
┌───────┼──────────┼──────────┼───────────────┐
│       ▼          ▼          ▼               │
│   ┌────────────────────────────────┐        │
│   │   playwright-mcp-orchestrator  │        │
│   │                                │        │
│   │  - Tab group isolation         │        │
│   │  - Session routing             │        │
│   │  - Uses official @playwright/mcp│       │
│   └────────────────────────────────┘        │
└─────────────────────────────────────────────┘

Key design decisions

1. Delegates to official @playwright/mcp — not a reimplementation. New tools and features from Microsoft are available automatically.
2. Shared user profile — all agents see the same cookies, logins, localStorage.
3. Tab isolation — each agent operates on its own tabs, no interference.
4. CDP connection — connects to a running Chrome instance via --remote-debugging-port.

Status

Early development. The CDP foundation has been validated:

• Chrome 145 with --remote-debugging-port=9222 + --user-data-dir works
• Multiple playwright-core connections via connectOverCDP to the same browser work
• Each connection can create and manage its own tabs independently
• All connections share the same BrowserContext (cookies, logins, storage)

Chrome Setup

Chrome 136+ silently ignores --remote-debugging-port on the default profile directory. You must use --user-data-dir pointing to a non-default path.

Copy your profile (preserves all logins)

# Quit Chrome first
osascript -e 'tell application "Google Chrome" to quit'

# Copy profile
cp -r ~/Library/Application\ Support/Google/Chrome /tmp/chrome-cdp-profile

# Launch with CDP
open -a "Google Chrome" --args \
  --user-data-dir=/tmp/chrome-cdp-profile \
  --remote-debugging-port=9222

Verify CDP is working

curl -s http://127.0.0.1:9222/json/version

Research

Why not existing solutions?

Why not other browser frameworks?

The multi-agent shared-profile problem is unsolved

No well-maintained project provides: real user profile + multiple concurrent agents + tab isolation + MCP interface. This project aims to be the first.

License

MIT