playwriter-browser-mcp

v0.1.4

Published

5 days ago

MCP server bridging Playwriter's Chrome extension with Playwright-style structured tools for VisionClaw

0High
0Medium
0Low

redux888999

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             # 运行测试