Playwriter Browser MCP

一个独立的 MCP (Model Context Protocol) 服务，通过 Playwriter Chrome 扩展连接用户的真实浏览器，提供 37 个结构化浏览器自动化工具。

对于任意 Agent 来说，只需添加一个 MCP 配置，就能操控用户真实的 Chrome 浏览器（带完整登录态）—— 无需 --remote-debugging-port，不受 Chrome 136+ 安全限制。

为什么需要这个项目

方案	能用真实 Profile	结构化工具	不需要调试端口
Playwright MCP (@playwright/mcp)	❌	✅ 38 个工具	❌
Playwriter	✅	❌ 仅 1 个 execute	✅
Browser MCP (本项目)	✅	✅ 37 个工具	✅

Browser MCP = Playwriter 的连接方式 + Playwright MCP 的工具生态。

架构

AI Agent (Claude Code / VisionClaw / ...)
   │ MCP Protocol (HTTP / SSE)
   ▼
┌──────────────────────────────────┐
│  Browser MCP Server (port 3280)  │
│                                  │
│  37 个结构化工具:                 │
│  ├── browser_navigate            │
│  ├── browser_snapshot            │
│  ├── browser_click               │
│  ├── browser_type                │
│  ├── browser_take_screenshot     │
│  ├── ... (共 37 个)              │
│                                  │
│  连接层:                          │
│  Playwriter API → connectOverCDP │
└──────────────┬───────────────────┘
               │ WebSocket
               ▼
┌──────────────────────────────────┐
│  Playwriter Relay (port 19988)   │
│  (已有的 relay 或自动启动)        │
└──────────────┬───────────────────┘
               │ chrome.debugger API
               ▼
┌──────────────────────────────────┐
│  Chrome 浏览器 (用户真实 Profile) │
│  ├── 已登录的网站                 │
│  ├── Cookies / Sessions          │
│  └── Playwriter 扩展 (已安装)    │
└──────────────────────────────────┘

快速开始

前置条件

1. Chrome 浏览器 — 安装 Playwriter 扩展
2. Node.js >= 18
3. Playwriter CLI — npm install -g playwriter

启动

# 1. 安装依赖
npm install

# 2. 配置环境变量（可选）
cp .env.example .env

# 3. 启动
npm run dev

服务启动后，MCP 端点在 http://localhost:3280/mcp。

多 Profile 场景

如果 Chrome 登录了多个 Google 账号，需要指定连接哪个：

# 查看可用的 Profile
playwriter browser list

# 指定 Profile 启动
PLAYWRITER_EXTENSION_ID="profile:104623951740642372686" npm run dev

MCP 工具列表 (37 个)

导航

工具	说明
browser_navigate	导航到 URL，返回页面快照
browser_navigate_back	返回上一页

快照与截图

工具	说明
browser_snapshot	获取页面 accessibility tree（带 [ref] 标记，用于后续交互）
browser_take_screenshot	截图（支持 png/jpeg、全页、指定元素）

输入操作

工具	说明
browser_click	点击元素（通过 ref 定位）
browser_type	向元素输入文本
browser_press_key	按下键盘按键（Enter、Tab、Escape 等）
browser_hover	鼠标悬停在元素上
browser_drag	拖拽元素到目标
browser_select_option	在下拉框中选择选项
browser_fill_form	批量填写表单（文本框、复选框、单选按钮）

页面管理

工具	说明
browser_tabs	标签页管理（list / new / close / select）
browser_close	关闭当前页面
browser_wait_for	等待文本出现/消失或指定时间
browser_resize	调整浏览器窗口大小

代码执行

工具	说明
browser_evaluate	在页面中执行 JavaScript
browser_run_code	运行 Playwright 代码片段

观测

工具	说明
browser_console_messages	获取控制台日志
browser_network_requests	获取网络请求列表

文件与对话框

工具	说明
browser_file_upload	上传文件到 file input
browser_handle_dialog	处理 alert/confirm/prompt 弹窗

Vision（坐标操作）

工具	说明
browser_mouse_move_xy	移动鼠标到坐标
browser_mouse_click_xy	在坐标处点击
browser_mouse_drag_xy	从坐标 A 拖拽到坐标 B
browser_mouse_down	按下鼠标按键
browser_mouse_up	释放鼠标按键
browser_mouse_wheel	滚动鼠标滚轮

测试验证

工具	说明
browser_generate_locator	生成 Playwright locator（用于编写测试）
browser_verify_text_visible	验证文本在页面上可见
browser_verify_element_visible	验证元素可见
browser_verify_list_visible	验证列表包含指定项
browser_verify_value	验证元素的值

PDF 与追踪

工具	说明
browser_pdf_save	将页面保存为 PDF
browser_start_tracing	开始录制 Playwright trace
browser_stop_tracing	停止录制并保存 trace 文件

其他

工具	说明
browser_install	安装 Chromium 浏览器二进制文件
browser_session	诊断工具：检查连接状态（无需主动调用，连接是自动的）

接入方式

作为 HTTP MCP Server

{
  "mcpServers": {
    "browser": {
      "type": "http",
      "url": "http://localhost:3280/mcp"
    }
  }
}

接入 VisionClaw

在 VisionClaw 的 mcp-servers.json 中添加上述配置即可。Agent 无需任何额外操作，直接调用 browser_navigate 等工具，连接会自动建立。

工作流程示例

AI 使用这套工具的典型流程：

1. browser_navigate({ url: "https://x.com" })
   → 自动连接浏览器，导航到 X，返回页面快照

2. browser_snapshot()
   → 获取 accessibility tree，包含 [ref] 标记

3. browser_click({ ref: "compose-btn" })
   → 点击发帖按钮

4. browser_type({ ref: "tweet-input", text: "Hello World!" })
   → 输入帖子内容

5. browser_click({ ref: "post-btn" })
   → 发布

无需手动连接、创建 session、选择 tab —— 一切自动完成。

环境变量

变量	默认值	说明
MCP_PORT	3280	MCP HTTP 服务端口
PLAYWRITER_RELAY_PORT	19988	Playwriter WebSocket relay 端口
PLAYWRITER_RELAY_HOST	127.0.0.1	Relay 地址
PLAYWRITER_EXTENSION_ID	（自动检测）	多 Profile 时指定连接哪个扩展
OUTPUT_DIR	./output	截图、PDF、trace 文件输出目录

技术原理

传统方案需要 --remote-debugging-port 来让程序操控浏览器，但 Chrome 136+ 禁止在默认 Profile 上使用该参数。

本项目利用 Playwriter 的 Chrome 扩展，通过 chrome.debugger API 从浏览器内部获取 CDP 访问权限，再通过 WebSocket relay 转发给 Playwright。这样：

• ✅ 不需要 --remote-debugging-port
• ✅ 可以使用用户的真实 Chrome Profile（带登录态）
• ✅ 暴露 37 个结构化 MCP 工具（与 Playwright MCP 对齐）
• ✅ 连接自动建立，无需手动操作

开发

npm install          # 安装依赖
npm run dev          # 开发模式启动
npm run build        # 编译 TypeScript
npm run lint         # 类型检查
npm test             # 运行测试