Loading... # Playwriter Chrome 扩展 MCP 技术分析 # 一、概述 ## 1. 简介 ### A. 是什么 Playwriter 是一个基于 Chrome 扩展的 Model Context Protocol（MCP）服务器，为 AI 智能体提供浏览器自动化能力。与传统的 Playwright MCP 不同，Playwriter 通过浏览器扩展的方式工作，无需启动独立的 Chrome 实例。 ### B. 核心特点 - 无上下文膨胀：仅使用 1 个 execute 工具，相比其他方案节省 80% 上下文 - 浏览器扩展架构：在用户现有浏览器中运行，而非独立的自动化浏览器 - 完整 Playwright API：暴露完整的 Playwright API，而非有限的预设工具集 - 协作友好：用户可与 AI 在同一浏览器中协同工作 ### C. 适用场景 - AI 智能体需要控制浏览器执行任务 - 需要在现有浏览器会话中复现问题 - 需要绕过自动化检测的场景 - 远程环境（Devcontainers、VM、SSH）中的智能体控制本地浏览器 ## 2. 项目背景 Playwriter 由开发者 remorses 创建，旨在解决现有浏览器自动化 MCP 方案的问题： - Microsoft Playwright MCP 需要启动独立浏览器，资源消耗大 - BrowserMCP 和 Antigravity 暴露大量独立工具，占用上下文过多 - 现有方案难以绕过自动化检测系统 # 二、系统架构 ## 1. 架构设计 ### A. 组件说明 - Chrome 扩展：在浏览器中运行，通过 chrome.debugger API 与标签页通信 - WebSocket 服务器：本地中继服务器，监听 19988 端口 - MCP 客户端：AI 智能体（如 Claude），通过 execute 工具发送 Playwright 代码 - Playwright API：提供完整的浏览器自动化能力 ### B. 数据流向 1. AI 智能体通过 execute 工具发送 Playwright 代码 2. MCP 客户端将代码发送到本地 WebSocket 服务器 3. 服务器通过 CDP 路由将命令转发给 Chrome 扩展 4. 扩展通过 chrome.debugger API 控制已连接的标签页 5. 执行结果沿相同路径返回 ## 2. 连接状态 ```mermaid stateDiagram-v2 [*] --> Gray: 未连接 Gray --> Orange: 连接中 Orange --> Green: 连接成功 Orange --> Red: 连接失败 Green --> Red: 运行时错误 Red --> Gray: 断开 Green --> Gray: 用户断开 ```   **图标状态含义**： - 灰色：未连接到此标签页 - 绿色：已连接并准备就绪 - 橙色徽章（...）：正在连接 - 红色徽章（!）：连接错误 # 三、安装与配置 ## 1. 安装步骤 ### A. 安装 Chrome 扩展 1. 从 Chrome 网上应用店安装 Playwriter MCP 扩展 2. 将扩展固定到 Chrome 工具栏以便快速访问 ### B. 连接到标签页 1. 导航到想要控制的标签页 2. 点击 Playwriter MCP 扩展图标 3. 图标变绿表示连接成功 ### C. 配置 MCP 客户端 在 Claude Desktop 的 claude_desktop_config.json 中添加： ```json { "mcpServers": { "playwriter": { "command": "npx", "args": ["playwriter@latest"] } } } ``` 重启 MCP 客户端后即可使用。 ## 2. 远程环境配置 当智能体运行在 Devcontainers、VM 或 SSH 环境中时： ### A. 主机端（Chrome 运行位置） ```bash npx playwriter serve --token <secret> # 或使用环境变量 PLAYWRITER_TOKEN=<secret> npx playwriter serve ``` ### B. 容器/虚拟机端（智能体运行位置） ```bash export PLAYWRITER_HOST="host.docker.internal" export PLAYWRITER_TOKEN="<secret>" ``` 或使用 CLI 选项： ```bash npx playwriter --host host.docker.internal --token <secret> ``` # 四、核心功能 ## 1. MCP 工具接口 Playwriter 仅暴露一个 execute 工具，AI 智能体通过发送 Playwright 代码片段控制浏览器。 ```mermaid graph LR AI[AI Agent] -->|execute tool| MCP[MCP Server] MCP -->|Playwright Code| Relay[WebSocket Relay] Relay -->|CDP Command| Ext[Chrome Extension] Ext -->|chrome.debugger| Tab[Browser Tab] Tab -->|Result| Ext Ext -->|CDP Event| Relay Relay -->|Return Value| MCP MCP -->|Response| AI ```   ## 2. 可用操作 启用扩展后，AI 智能体可以： - 通过 execute 工具控制所有已启用的标签页 - 使用 Playwright 的 context 和 page API 切换标签页 - 以编程方式创建新标签页 - 对浏览器标签页运行任何 Playwright 代码 ## 3. 编程接口 也可以直接使用 playwright-core 编程： ```javascript import { chromium } from 'playwright-core' import { startPlayWriterCDPRelayServer, getCdpUrl } from 'playwriter' const server = await startPlayWriterCDPRelayServer() const browser = await chromium.connectOverCDP(getCdpUrl()) const context = browser.contexts()[0] const page = context.pages()[0] await page.goto('https://example.com') await page.screenshot({ path: 'screenshot.png' }) await browser.close() server.close() ``` # 五、对比分析 ## 1. 与 Playwright MCP 对比 | 特性 | Playwright MCP | Playwriter | |------|---------------|------------| | 浏览器实例 | 独立 Chrome | 用户现有浏览器 | | 协作能力 | 无法协作 | 与 AI 同浏览器协作 | | 资源消耗 | 高（独立实例） | 低（共享浏览器） | | 扩展支持 | 需要重新安装 | 复用现有扩展 | | 自动化检测 | 始终被检测 | 可临时断开绕过 | | 工作流 | 多窗口切换 | 单浏览器工作流 | ### A. 协作优势 - 与 AI 在同一浏览器中工作 - 在验证码或复杂交互时帮助 AI - 在现有页面上启动 MCP，精确复现 bug ### B. 扩展复用 - 继续使用已安装的广告拦截器 - 继续使用密码管理器 - 无需在自动化浏览器中重新配置 ### C. 绕过检测 - 通过断开扩展临时禁用 CDP/自动化 - 绕过 Google 登录等检测系统 - 重新连接继续自动化 ## 2. 与 BrowserMCP 对比 BrowserMCP 为每种浏览器操作创建独立工具，而 Playwriter 使用完整 Playwright API。 ### A. 上下文窗口效率 ```mermaid graph TB subgraph BrowserMCP["BrowserMCP (17+ tools)"] BM1[browser_navigate] BM2[browser_snapshot] BM3[browser_click] BM4[browser_hover] BM5[browser_type] BM6[browser_screenshot] BM7[browser_wait] BM8[...10 more tools] end subgraph Playwriter["Playwriter (1 tool)"] PW[execute<br/>Full Playwright API] end Context[LLM Context Window] BrowserMCP -->|占用 80%| Context Playwriter -->|占用 20%| Context style Playwriter fill:#c8e6c9 style BrowserMCP fill:#ffcdd2 ```   ### B. 工具数量对比 BrowserMCP 支持的工具： - 导航：browser_navigate、browser_go_back、browser_go_forward - 页面检查：browser_snapshot、browser_screenshot、browser_get_console_logs - 交互：browser_click、browser_hover、browser_type、browser_select_option、browser_press_key - 工具：browser_wait Playwriter：仅 execute 工具，通过 Playwright API 实现所有功能。 ## 3. 与 Antigravity (Jetski) 对比 ### A. 上下文窗口问题 Jetski 暴露 17+ 个浏览器工具，每个工具定义消耗上下文窗口空间： - 参数模式 - 工具描述 - 使用示例 这导致 Antigravity 必须为每次浏览器操作生成子智能体，增加延迟和间接层。 ### B. Playwriter 优势 | 特性 | Jetski | Playwriter | |------|--------|------------| | 工具数量 | 17+ | 1 | | 子智能体生成 | 每次都需要 | 无需生成 | | 延迟 | 高 | 低 | | 上下文使用 | 大幅占用 | 最小占用 | | API 知识复用 | 需要学习 | 已知 Playwright | | 能力 | 有限预设操作 | 完整 Playwright API | # 六、安全设计 ## 1. 架构安全  ### A. 本地 WebSocket 服务器 - MCP 启动时在 localhost:19988 创建单例 WebSocket 服务器 - 不发送 CORS 头，阻止任何网页或远程服务器连接 - 只有本地运行的进程可以建立连接 ### B. 用户控制访问 - 扩展只能控制用户明确点击扩展图标的标签页 - 绿色图标明确指示已连接的标签页 - Chrome 在受控标签页显示自动化横幅 ## 2. 可控范围 ### A. 可以控制的 - 用户明确连接的标签页（通过点击扩展图标） - 通过自动化创建的新标签页 ### B. 不能控制的 - 远程访问：外部网站或服务器无法连接到 WebSocket - 被动监控：扩展无法读取未连接的标签页 - 自动传播：调试器不会自动附加到手动打开的新标签页 # 七、已知问题 ## 1. about:blank 问题 - **现象**：所有页面 URL 在每次 MCP 会话重启时返回 about:blank - **原因**：Chrome 中 chrome.debugger 扩展 API 的某些隐藏状态 - **解决方案**：重启 Chrome 浏览器。仅重启扩展工作者无法修复 ## 2. 主题切换问题 - **现象**：连接 MCP 到页面时，浏览器可能切换到浅色模式 - **原因**：Playwright 通过 CDP 在启动时自动发送 emulate media 命令 - **解决方案**：如需更改此行为，可以在相关 Issue 上投票 # 八、技术细节 ## 1. Chrome DevTools Protocol (CDP) - Playwriter 使用 CDP 与浏览器通信 - 扩展通过 chrome.debugger API 访问 CDP - 支持 CDP 命令和事件的完整路由 ## 2. WebSocket 路由 - /extension：扩展连接端点 - /cdp/:id：CDP 命令和事件路由 - attach/detach：目标事件处理 ## 3. 中继服务器 - 在扩展和 MCP 客户端之间中继消息 - 支持远程环境配置（host、token） - 自动管理连接状态 # 九、应用场景 ## 1. 开发调试 - 在现有浏览器会话中复现 bug - 与 AI 协作解决验证码和复杂交互 - 使用现有开发工具和扩展 ## 2. 自动化测试 - 绕过自动化检测系统 - 在真实浏览器环境中测试 - 复用用户配置和会话 ## 3. 远程智能体 - Devcontainers 中的智能体控制本地浏览器 - VM 或 SSH 环境中的智能体访问浏览器 - 保持浏览器在主机上，智能体在隔离环境中 *** ## 参考资料 1. [remorses/playwright GitHub Repository](https://github.com/remorses/playwriter) 2. [Playwright Official Documentation](https://playwright.dev/) 3. [Chrome Extension APIs - chrome.debugger](https://developer.chrome.com/docs/extensions/reference/api/debugger) 4. [Microsoft Playwright MCP](https://github.com/microsoft/playwright-mcp) 最后修改：2026 年 01 月 15 日 © 允许规范转载 赞 如果觉得我的文章对你有用，请随意赞赏