使用说明

终极剧作家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浏览器（保留您的个人资料、扩展程序、书签）

比较

特点	终极剧作家mcp	@剧作家/mcp	浏览器使用mcp
多代理选项卡隔离	✅ 标签组 `groupId`	❌ 单次会议	❌ 单次会议
跨代理共享Cookie	✅ 相同的浏览器上下文	N/A	N/A
连接到现有的Chrome浏览器	✅ CDP	❌ 启动新浏览器	❌ 启动新浏览器
Chrome中的可视选项卡组	✅ 扩展	❌	❌
持久选项卡注册表	✅ 重新启动后幸存	❌	❌
辅助功能树快照	✅ 元素引用（e1，e2…）	✅	❌ 基于屏幕截图
开源	✅ MIT	✅ 阿帕奇-2.0	✅ 麻省理工学院

特性

✅ 选项卡隔离 -每个代理通过唯一的 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_tab_group`	创建/列出/删除选项卡组以进行隔离	`action`, `name`, `color`, `groupId`
`browser_tabs`	列出、创建、关闭或选择选项卡	`action`, `groupId`, `targetId`, `index`
`browser_navigate`	导航到URL	`url`, `targetId`
`browser_snapshot`	使用引用捕获可访问性树	`targetId`
`browser_click`	单击元素	`ref`, `targetId`
`browser_type`	在元素中键入文本	`ref`, `text`, `targetId`
`browser_hover`	将鼠标悬停在元素上	`ref`, `targetId`
`browser_press_key`	按键盘键	`key`, `targetId`
`browser_fill_form`	填写多个表单字段	`fields`, `targetId`
`browser_wait_for`	等待条件	`text`, `selector`, `url`, `loadState`, `targetId`
`browser_checkpoint`	为选项卡捕获结构化检查点	`name`, `targetId`, `collectors`
`browser_checkpoint_report`	从存储的检查点生成报告	`format`, `resultsDir`

检查点

使用 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/会话，但只能看到自己的标签页！

选项卡组生命周期

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

组状态将持久化为 ~/.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 <url>  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 <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 <path>
                        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:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.user.chrome-debug</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Applications/Google Chrome.app/Contents/MacOS/Google Chrome</string>
        <string>--remote-debugging-port=9222</string>
        <string>--user-data-dir=/Users/YOUR_USERNAME/chrome-debug-profile</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>

加载：

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规范 -模型上下文协议
剧作家 -浏览器自动化库