Ultimate Playwright MCP

终极剧作家MCP

](https://www.npmjs.com/package/ultimate-playwright-mcp) ](https://www.npmjs.com/package/ultimate-playwright-mcp)  

多代理Playwright MCP服务器，通过标签隔离 targetId允许多个Claude实例（或其他MCP客户端）共享一个Chrome浏览器，同时保持独立的标签组。

为什么是终极剧作家？

官方 @playwright/mcp 为您提供浏览器控制 单智能体但如果你有 多个代理 共享一个浏览器？

终极剧作家MCP 通过以下方式解决此问题 选项卡组隔离:

• 🔀 多代理选项卡组 --每个代理创建一个 groupId 并且只看到自己的选项卡
• 🍪 共享Cookie和会话 --所有代理共享相同的BrowserContext（登录一次，每个人都经过身份验证）
• 🎨 可视化Chrome选项卡组 --配套扩展程序将标签组织成颜色编码的Chrome标签组
• 💾 持久注册表 --选项卡组在MCP服务器重启后仍然存在(~/.ultimate-playwright-mcp/tab-groups.json)
• 🔌 连接到现有Chrome --使用CDP连接到正在运行的Chrome浏览器（保留您的个人资料、扩展程序、书签）

比较

特性

• ✅ 选项卡隔离 -每个代理通过唯一的 targetId
• ✅ 共享Cookie -所有代理共享相同的BrowserContext（Cookie、会话、本地存储）
• ✅ 并行执行 -多个代理可以同时运行而不受干扰
• ✅ CDP连接 -通过Chrome DevTools协议连接到现有的Chrome
• ✅ 本机页面检查点 -捕获结构化工件并生成报告 targetId
• ✅ 战斗测试 -摘录自 开爪 （麻省理工学院许可）

安装

npm install -g ultimate-playwright-mcp

或者直接使用npx运行：

npx ultimate-playwright-mcp --cdp-endpoint http://localhost:9222

快速开始

1.通过远程调试启动Chrome

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/chrome-debug

# Linux
google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug

# Windows
"C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe" ^
  --remote-debugging-port=9222 ^
  --user-data-dir=C:\\temp\\chrome-debug

2.配置克劳德桌面

添加 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "ultimate-playwright": {
      "command": "npx",
      "args": [
        "ultimate-playwright-mcp",
        "--cdp-endpoint",
        "http://localhost:9222"
      ]
    }
  }
}

3.重新启动克劳德桌面

Claude现在可以访问带有标签隔离的浏览器控制工具。

使用示例

User: Open two tabs and navigate them independently

Claude: I'll create two tabs with separate targetIds:

1. browser_tabs({ action: "new" })
   → **targetId: ABC123...**

2. browser_tabs({ action: "new" })
   → **targetId: XYZ789...**

3. browser_navigate({ targetId: "ABC123...", url: "https://github.com" })
4. browser_navigate({ targetId: "XYZ789...", url: "https://google.com" })

Both tabs are now navigated independently!

可用工具

检查点

使用 browser_checkpoint 当您希望持续捕获当前页面以供以后查看或生成报告时。

• 检查点的范围为已解决的 targetId，因此它们使用此服务器的选项卡隔离模型。
• 文物和清单写在 ~/.ultimate-playwright-mcp/checkpoints 默认情况下。
• 生成的报告写在 ~/.ultimate-playwright-mcp/checkpoints/report.

例子：

1. browser_checkpoint({ targetId: "ABC123", name: "after-login" })
2. browser_checkpoint_report({ format: "html" })

选项卡组（多用户隔离）

当多个用户或代理共享一个浏览器实例时，选项卡组会保留每个人的 标签被隔离。每个会话都创建自己的组，所有选项卡操作都有作用域 对于这个群体。

User: Research product pricing

Claude: I'll create a tab group first, then open tabs within it.

1. browser_tab_group({ action: "create", name: "pricing-research", color: "blue" })
   → **groupId: g_a1b2c3d4e5f6**

2. browser_tabs({ action: "new", groupId: "g_a1b2c3d4e5f6", url: "https://example.com/pricing" })
   → **targetId: ABC123...**

3. browser_tabs({ action: "list", groupId: "g_a1b2c3d4e5f6" })
   → Only shows tabs in this group (not other users' tabs)

同时，同一服务器上的另一个用户：

1. browser_tab_group({ action: "create", name: "docs-review", color: "green" })
   → **groupId: g_x9y8z7w6v5u4**

2. browser_tabs({ action: "new", groupId: "g_x9y8z7w6v5u4", url: "https://docs.example.com" })
   → **targetId: XYZ789...**

两个用户共享相同的Cookie/会话，但只能看到自己的标签页！

选项卡组生命周期

1. 创建 会话开始时的小组
2. 打开选项卡 组内使用 groupId
3. 工作 使用标签 targetId 和以前一样
4. 删除 完成后的组（可选关闭所有选项卡）

组状态将持久化为 ~/.ultimate-playwright-mcp/tab-groups.json 所以 在MCP服务器重启后幸存。

建筑

┌─────────────────────────────────────────────┐
│        Single Chrome Process                │
│    (--remote-debugging-port=9222)           │
│  ┌─────────────────────────────────────┐   │
│  │     Single BrowserContext            │   │
│  │  (shared cookies, storage)           │   │
│  │                                      │   │
│  │  Group: alice (blue)                 │   │
│  │  ┌─────┐ ┌─────┐                    │   │
│  │  │ Tab │ │ Tab │                    │   │
│  │  │  A  │ │  B  │                    │   │
│  │  └─────┘ └─────┘                    │   │
│  │                                      │   │
│  │  Group: bob (green)                  │   │
│  │  ┌─────┐ ┌─────┐ ┌─────┐            │   │
│  │  │ Tab │ │ Tab │ │ Tab │            │   │
│  │  │  C  │ │  D  │ │  E  │            │   │
│  │  └─────┘ └─────┘ └─────┘            │   │
│  └─────────────────────────────────────┘   │
└─────────────────────────────────────────────┘
                   ↑
           CDP Connection
                   ↓
┌─────────────────────────────────────────────┐
│    ultimate-playwright-mcp (MCP Server)     │
│    - Tab routing via targetId               │
│    - Tab groups via groupId                 │
│    - Shared ownership registry (JSON file)  │
│    - Stdio transport                        │
└─────────────────────────────────────────────┘
         ↓           ↓           ↓
   ┌─────────┐ ┌─────────┐ ┌─────────┐
   │ Alice   │ │  Bob    │ │ Charlie │
   │ (Claude)│ │ (Claude)│ │ (Cursor)│
   └─────────┘ └─────────┘ └─────────┘

MCP配置

光标/风帆/通用MCP客户端

{
  "mcpServers": {
    "ultimate-playwright": {
      "command": "npx",
      "args": ["ultimate-playwright-mcp", "--cdp-endpoint", "http://localhost:9222"]
    }
  }
}

带环境变量

{
  "mcpServers": {
    "ultimate-playwright": {
      "command": "npx",
      "args": ["ultimate-playwright-mcp"],
      "env": {
        "CDP_ENDPOINT": "http://localhost:9222"
      }
    }
  }
}

CLI选项

ultimate-playwright-mcp [options]

Options:
  --cdp-endpoint   CDP endpoint URL (e.g., http://localhost:9222)
                        Can also use CDP_ENDPOINT env var.
                        If omitted, daemon-managed Chrome is started lazily on first tool call.
  --agent-id        Optional agent ID for logging/debugging
                        Can also use AGENT_ID env var
  --keep-alive          Auto-restart daemon-managed Chrome if it exits
                        Use --no-keep-alive for testing workflows where you want Chrome to stay down after kill
                        Default: disabled (no auto-restart)
                        Can also use KEEP_ALIVE env var (set to "false" to disable)
  --checkpoint-output-dir 

                        Root directory for checkpoint manifests, artifacts, and reports
                        Can also use CHECKPOINT_OUTPUT_DIR env var
  -V, --version         Output version number
  -h, --help            Display help

多代理设置

运行多个Claude代码实例

每个实例都连接到同一个MCP服务器，并获得隔离的选项卡：

1号航站楼：

claude-code --mcp-config ./mcp-config.json
# Agent A creates tabs with targetIds starting from ABC...

2号航站楼：

claude-code --mcp-config ./mcp-config.json
# Agent B creates tabs with targetIds starting from XYZ...

两个代理共享Cookie和会话，但在不同的选项卡上操作！

持久Chrome设置（macOS）

对于使用调试端口自动启动的Chrome实例：

创建 ~/Library/LaunchAgents/com.user.chrome-debug.plist:

    Label
    com.user.chrome-debug
    ProgramArguments
    
        /Applications/Google Chrome.app/Contents/MacOS/Google Chrome
        --remote-debugging-port=9222
        --user-data-dir=/Users/YOUR_USERNAME/chrome-debug-profile
    
    RunAtLoad
    
    KeepAlive
    

加载：

launchctl load ~/Library/LaunchAgents/com.user.chrome-debug.plist

发展

# Install dependencies
npm install

# Build
npm run build

# Type check
npm run type-check

# Lint
npm run lint

# Watch mode
npm run watch

许可证

麻省理工学院

归因

此项目从中提取浏览器控制代码 开爪 （麻省理工学院授权），提供经过实战测试的标签隔离和Playwright集成。

关键提取成分：

• CDP会话管理(pw-session.ts)
• 浏览器操作(pw-tools-*.ts)
• 基于角色的元素引用(pw-role-snapshot.ts)

链接

• 开爪 -浏览器控制代码的来源
• MCP规范 -模型上下文协议
• 剧作家 -浏览器自动化库