Playwriter Browser MCP

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 个)

导航

快照与截图

输入操作

页面管理

代码执行

观测

文件与对话框

Vision（坐标操作）

测试验证

PDF 与追踪

其他

接入方式

作为 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 —— 一切自动完成。

环境变量

技术原理

传统方案需要 --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             # 运行测试