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 扩展 (已安装)    │
└──────────────────────────────────┘

快速开始

前置条件

Chrome 浏览器 — 安装 Playwriter 扩展
Node.js >= 18
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_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             # 运行测试

Playwriter Browser MCP