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. 连接状态

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 中添加：

{
  "mcpServers": {
    "playwriter": {
      "command": "npx",
      "args": ["playwriter@latest"]
    }
  }
}

重启 MCP 客户端后即可使用。

2. 远程环境配置

当智能体运行在 Devcontainers、VM 或 SSH 环境中时：

A. 主机端（Chrome 运行位置）

npx playwriter serve --token <secret>
# 或使用环境变量
PLAYWRITER_TOKEN=<secret> npx playwriter serve

B. 容器/虚拟机端（智能体运行位置）

export PLAYWRITER_HOST="host.docker.internal"
export PLAYWRITER_TOKEN="<secret>"

或使用 CLI 选项：

npx playwriter --host host.docker.internal --token <secret>

四、核心功能

1. MCP 工具接口

Playwriter 仅暴露一个 execute 工具，AI 智能体通过发送 Playwright 代码片段控制浏览器。

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 编程：

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 对比

A. 协作优势

• 与 AI 在同一浏览器中工作
• 在验证码或复杂交互时帮助 AI
• 在现有页面上启动 MCP，精确复现 bug

B. 扩展复用

• 继续使用已安装的广告拦截器
• 继续使用密码管理器
• 无需在自动化浏览器中重新配置

C. 绕过检测

• 通过断开扩展临时禁用 CDP/自动化
• 绕过 Google 登录等检测系统
• 重新连接继续自动化

2. 与 BrowserMCP 对比

BrowserMCP 为每种浏览器操作创建独立工具，而 Playwriter 使用完整 Playwright API。

A. 上下文窗口效率

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 优势

六、安全设计

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
2. Playwright Official Documentation
3. Chrome Extension APIs - chrome.debugger
4. Microsoft Playwright MCP