MCP Playwright Browser

MCP剧作家浏览器服务器

A生产级 模型上下文协议（MCP）服务器 通过Playwright，人工智能助手可以完全控制浏览器——使用DOM+可访问性树+可视化的混合方法。为真实世界的代理自动化而构建：作业应用程序、网络抓取、表单填写和复杂的多标签工作流。

v2.0是一个完整的重写。 服务器从680行和23个工具增长到近5000行和71个工具，具有模块化架构、令牌优化的捕获配置文件、硬负载预算和完整的测试套件。

______________________________________________________________________

目录

• v2.0中的新增功能
• v1与v2比较
• 运作原理
• 快速开始
• 安装
• 配置文件启动器
• 全部71个MCP工具
• 建筑
• 令牌效率：捕获配置文件
• 常见用例
• 环境变量
• 项目结构
• 故障排除
• 安全与隐私
• 道德使用
• 许可证

______________________________________________________________________

v2.0中的新增功能

问题v1

v1是一个有效的概念验证。它可以浏览页面并提取作业。但是，当与Gemini CLI一起用于实际任务时——填写应用程序表单、导航多标签流、处理下载——它遇到了严重的限制：

• 代币浪费：每个工具响应都会丢弃它发现的所有内容。一 browser.snapshot 在一个复杂的页面上，一次调用就可以将50KB+的内存推入Gemini的上下文窗口，从而迅速耗尽预算。
• 不支持多标签：如果一个链接打开了一个新的标签页（在求职申请中很常见），双子座就无法切换到它。
• 无表单智能：填写表格需要手动点击说明。无法询问“哪些字段仍然为空？”或“填写所有必填字段”
• 易碎的仅DOM导航：影子DOM、iframe和混淆的元素ID导致了失败，没有回退。
• 无会话持久性：每次跑步都是从头开始。一次又一次登录浪费了时间，并触发了机器人检测。
• 无安全护栏：人工智能可以在磁盘上的任何地方写入文件，运行任意JS，或创建自己的自动化脚本——不受保护。
• 整体的：一个680行的文件，没有测试。

v2.0解决了什么问题

在v2.0中，每个问题都有一个特定的解决方案：

______________________________________________________________________

v1与v2比较

什么保持不变

• 确实，作业提取器（生产级、多选择器、重复数据删除）
• 谷歌搜索提取器（同意处理、URL去模糊）
• 隐身模式（隐藏Web驱动程序、用户代理欺骗）
• CDP连接到真正的Chrome
• 可视化快照+基于坐标的点击

______________________________________________________________________

运作原理

You / Gemini CLI
      │
      │ natural language prompt
      ▼
  Gemini CLI ──── loads MCP config ────► playwrightBrowser MCP server
                                               │
                              ┌────────────────┤
                              │                │
                         71 MCP Tools     Payload Budget
                         (browser.*)     (280KB ceiling)
                         (forms.*)       (capture profiles)
                         (files.*)       (retryWith hints)
                         (jobs.*)
                         (search.*)
                              │
                    ┌─────────┤──────────┐
                    │         │          │
               Playwright  CDP API   Security
               (browser)  (A11y,    (path
                          network,  allowlist)
                          clicks)
                    │
               Chrome / Chromium

捕获阶梯

每个配置文件都指示Gemini按顺序尝试工具，首先是最便宜的：

1. browser.snapshot     → plain text summary       (cheapest, ~6KB in light mode)
2. browser.list         → interactive elements      (structured, ~8KB)
3. browser.query_dom    → targeted selector query   (focused, ~10KB)
4. browser.take_snapshot→ A11y tree with UIDs       (rich, only when uid-clicking needed)
5. browser.visual_snapshot → screenshot + bbox map  (most expensive, last resort)

Gemini只会在更便宜的工具没有所需的东西时升级为更昂贵的工具。这就是为什么v2.0使用的令牌比v1.0少得多的核心。

有效载荷预算

每一个工具响应都会通过 enforcePayloadCeiling() 在发送给双子座之前：

1. 以字节为单位测量响应大小
2. 如果小于280KB→ 按原样发送
3. 如果结束→ 渐进截断：数组收缩，字符串截断，字段删除
4. 始终包括 retryWith 提示Gemini下次要减少哪些参数
5. 绝对楼层： {truncated: true} --双子座永远不会得到上下文崩溃的回应

______________________________________________________________________

快速开始

# Clone
git clone https://github.com/Mhrnqaruni/mcp-playwright-browser.git
cd mcp-playwright-browser

# Install
npm install
npx playwright install chromium

# Run (interactive mode - chat with Gemini)
scripts\run-dom-headless.bat

# Run (one-shot automation)
scripts\run-dom-headless.bat -p "Go to https://example.com and extract the page title"

# Run with real Chrome (for logged-in sessions)
scripts\run-chrome-profile.bat --kill-chrome

______________________________________________________________________

安装

先决条件

• Node.js 18+
• npm
• Gemini CLI: npm install -g @google/gemini-cli 然后 gemini auth login
• 谷歌浏览器 （适用于CDP和铬型材模式）

设置

1.安装依赖项

npm install
npx playwright install chromium

2.配置MCP服务器路径

编辑 .gemini/settings.json 并设置 cwd 到您的仓库位置：

{
  "mcpServers": {
    "playwrightBrowser": {
      "command": "node",
      "args": ["src/mcp-browser-server.js"],
      "cwd": "C:/path/to/mcp-playwright-browser"
    }
  }
}

3.（可选）禁用Chrome后台应用程序

防止配置文件锁定：

Chrome Settings → Advanced → System →
☐ Continue running background apps when Google Chrome is closed

4.验证

scripts\run-dom-headless.bat -p "Use MCP server playwrightBrowser. Launch browser. Go to https://example.com. Take a snapshot. Close."

______________________________________________________________________

配置文件启动器

每 .bat 该文件预先配置了所有内容（浏览器类型、隐身、配置文件、环境变量），并使用正确的系统指令启动Gemini。您永远不需要手动配置Gemini。

可用配置文件

互动模式（聊天）

# Start Gemini and chat with it
scripts\run-chrome-profile.bat --kill-chrome

# Then just type:
# "Fill out the job application at [URL] using my CV"
# "Go to LinkedIn and apply to the first 5 jobs"
# "Extract all AI engineer jobs from Indeed and save them"

单次模式（自动化）

# Run a task and get a log file
scripts\run-dom-headless.bat -p "Your full task here"

# With custom output
scripts\run-dom-headless.bat -p "Extract 50 jobs from Indeed" --output logs\jobs.log

# Chrome profile one-shot
scripts\run-chrome-profile.bat --kill-chrome -p "Submit application at [URL]" --output logs\apply.log

日志会自动保存到 logs/ 带有时间戳。

个人资料详细信息

run-dom-headless.bat --最快

• Chromium无头（无GUI）
• 最适合：批量提取、抓取、后台任务
• 代币使用率：最低（无截图）

run-visual-headful.bat --调试

• 铬合金，带可见窗口
• 基于屏幕截图的导航可用
• 最适合：故障排除、目视验证

run-chrome-profile.bat --经过身份验证的会话

• 使用现有登录配置文件的真实Chrome
• 已登录Gmail、LinkedIn、求职网站
• 使用 --kill-chrome 开始前释放配置文件
• 最适合：工作申请、经过身份验证的抓取

run-cdp-profile.bat --最大隐身能力

• 通过Chrome DevTools协议连接到真实的Chrome
• 网站最难检测到自动化
• 最适合：屏蔽Playwright/Chromium的网站
• 启动前自动关闭使用配置文件的任何现有Chrome

run-cdp-profile-persist.bat --长时间会议

• 具有持久浏览器的CDP模式（在任务之间不关闭）
• 最适合：浏览器状态必须存活的多步骤工作流

______________________________________________________________________

全部71个MCP工具

捕获配置文件控制

浏览器生命周期

多标签管理

导航

事件和对话处理

会话和Cookie管理

滚动控制

页面阅读和快照

元素交互

视觉导航

数据提取

表单自动化

可观测性

文件操作

专业提取器（生产示例）

______________________________________________________________________

建筑

模块结构

src/
├── mcp-browser-server.js      # Main server: tool registration, env config, middleware
├── extractors.js              # Indeed + Google specialized extractors
├── browser/
│   ├── pages.js               # Multi-tab page manager (stable pageIds)
│   ├── snapshot.js            # A11y tree via CDP Accessibility.getFullAXTree
│   ├── capture-profiles.js    # light/balanced/full × low/high = 30 preset configs
│   ├── payload-budget.js      # Hard 280KB response ceiling with graceful truncation
│   ├── cdp.js                 # CDP session, click/hover/scroll by backendNodeId
│   ├── dom-version.js         # DOM mutation tracking, frame management
│   ├── forms.js               # Form audit + intelligent form fill
│   ├── observability.js       # Console + network request capture via CDP
│   └── wait.js                # Smart wait: selector, text, uid
└── security/
    └── paths.js               # Read/write path allowlist enforcement

工具注册中间件

每个工具都要经过一个在处理程序之前和之后运行的包装器：

AI calls tool
      │
      ▼
assign requestId
      │
      ▼
run handler
      │
      ▼
normalize errors (structured, no stack traces)
      │
      ▼
add envelope (ok, requestId, timestamp, url, domVersion)
      │
      ▼
enforcePayloadCeiling (truncate if > 280KB)
      │
      ▼
send to AI

这意味着每个工具都会自动受益于错误安全和有效载荷预算，而无需为每个工具编写任何额外代码。

UID系统

A11y快照(browser.take_snapshot)以以下格式为每个节点分配一个稳定的UID ax-{nodeId}，与CDP联系在一起 backendDOMNodeId。然后，此UID可以与以下对象一起使用：

• browser.click({ uid: "ax-123" }) --直接通过CDP在后端节点上单击
• browser.scroll_to_uid({ uid: "ax-123" }) --先将其滚动到视图中
• browser.wait_for({ uid: "ax-123" }) --等到它可见

CDP原生点击比基于选择器的点击更可靠，因为它们绕过CSS选择器解析，即使在Shadow DOM中也能工作。

______________________________________________________________________

令牌效率：捕获配置文件

这是现实世界中最重要的v2.0功能。

问题

AI上下文窗口是有限的。每个工具响应都会消耗令牌。一个天真的实施方式，每次通话都会迅速耗尽预算。

解决方案：三种配置文件

在会话开始时设置一次配置文件，随后的每次工具调用都会自动使用适当的限制：

browser.set_capture_profile({ profile: "light" })

每个轮廓有两个细节级别

在每个配置文件中，工具都接受 detail: "low" 或 detail: "high":

browser.snapshot({ detail: "low" })   # minimal, fast
browser.snapshot({ detail: "high" })  # more text, links, headings, form summary

实践中的捕获阶梯

配置文件系统说明教导Gemini仅在需要时升级：

✅ "I need to find the Apply button"
→ browser.snapshot (low)           # did I find it in plain text? usually yes
→ browser.list (low)               # still looking? check interactive elements
→ browser.take_snapshot (low)      # need uid for reliable click? A11y tree
→ browser.visual_snapshot (low)    # shadow DOM / can't find it at all? visual fallback

在 light 在模式下，整个梯形图的令牌成本比v1.0的单转储方法低约8倍。

硬有效载荷预算

即使有捕获配置文件，有些页面也很庞大。有效载荷预算是一个安全网：

• 默认上限： 每个响应280KB
• 如果超过：逐步截断（数组→ 字符串→ 对象键）
• 包含 retryWith 字段： { detail: "low", maxItems: 80, limit: 20 }
• Gemini读取此信息并使用较小的参数重试
• 绝对回退： { truncated: true, truncationReason: "..." }

预算是可配置的： MCP_MAX_RESPONSE_BYTES=150000 对于更严格的环境。

______________________________________________________________________

常见用例

工作申请（Chrome配置文件）

# Start with your real logged-in Chrome
scripts\run-chrome-profile.bat --kill-chrome

双子座：

Set capture profile to light.
Go to [application URL].
Run form_audit to see all required fields.
Fill them using fill_form with my details from Applied Jobs/CODEX/maincv.md.
Before submitting, take a screenshot and ask me to confirm.

批量作业报废（无头）

scripts\run-dom-headless.bat -p "Use playwrightBrowser. Launch browser headless. Go to https://ae.indeed.com/q-ai-engineer-l-dubai-jobs.html. Extract jobs with jobs.extract_indeed limit 20, save to output/indeed/page-1. Go to next page with jobs.indeed_next_page. Extract again, save to output/indeed/page-2. Close."

会话持久性（登录一次，重用）

# First time: login manually and export session
scripts\run-cdp-profile.bat

双子座：

Go to linkedin.com and wait for me to log in.
After I confirm logged in, run browser.export_storage_state to output/linkedin-session.json.

下一次：

Run browser.import_storage_state from output/linkedin-session.json.
Go to linkedin.com — should be logged in already.

谷歌表单自动化

scripts\run-dom-headless.bat

双子座：

Go to [Google Form URL].
Run forms.google_audit to see all questions.
Fill each question using the appropriate forms.google_set_* tool.
Run forms.google_audit again to verify all answered.
Submit.

PDF简历阅读

双子座可以直接阅读你的简历，而无需粘贴：

Read my CV from Applied Jobs/CODEX/maincv.md using files.read_text.
Or read the PDF version: files.read_pdf_text from Applied Jobs/CODEX/CV.pdf.
Use that information to fill the job application form.

使用可视化模式进行调试

scripts\run-visual-headful.bat

双子座：

Go to [URL].
Take a visual_snapshot and save to output/debug.png.
Tell me what you see and identify any unusual elements.

______________________________________________________________________

环境变量

所有变量都有双重名称，以兼容Gemini CLI。发射器同时设置了以下两项：

为什么有双重名字？ Gemini CLI会清理环境变量，并可能进行剥离 MCP_* 前缀键。这 GEMINI_CLI_MCP_* 变量绕过此筛选。服务器读取这两个变量，并使用设置的变量。

______________________________________________________________________

项目结构

mcp-playwright-browser/
│
├── src/
│   ├── mcp-browser-server.js        # Main server (71 tools, middleware, env config)
│   ├── extractors.js                # Indeed + Google production extractors
│   ├── browser/
│   │   ├── pages.js                 # Multi-tab page manager
│   │   ├── snapshot.js              # A11y tree (CDP Accessibility API)
│   │   ├── capture-profiles.js      # Token budget profiles (light/balanced/full)
│   │   ├── payload-budget.js        # Hard response size ceiling
│   │   ├── cdp.js                   # CDP primitives (click, hover, scroll by nodeId)
│   │   ├── dom-version.js           # DOM mutation tracking + frame management
│   │   ├── forms.js                 # Form audit + intelligent fill
│   │   ├── observability.js         # Console + network capture
│   │   └── wait.js                  # Smart wait (selector, text, uid)
│   ├── security/
│   │   └── paths.js                 # File read/write path allowlist
│   └── tests/
│       ├── page-manager-test.js
│       ├── security-paths-test.js
│       ├── snapshot-uid-test.js
│       ├── uid-click-fill-test.js
│       ├── elementid-no-stale-test.js
│       ├── wait-for-test.js
│       ├── form-audit-fill-test.js
│       ├── console-network-test.js
│       ├── visual-coords-test.js
│       ├── frame-domversion-test.js
│       ├── cdp-hover-test.js
│       ├── browser-events-test.js
│       ├── storage-state-test.js
│       ├── capture-profiles-test.js
│       ├── payload-budget-test.js
│       ├── google-form-test.js
│       ├── google-test.js
│       └── indeed-test.js
│
├── scripts/
│   ├── run-dom-headless.bat          # Fastest: headless Chromium
│   ├── run-visual-headful.bat        # Visual: Chromium + screenshots
│   ├── run-chrome-profile.bat        # Auth: real Chrome with your profile
│   ├── run-cdp-profile.bat           # Stealth: CDP mode
│   ├── run-cdp-profile-screen.bat    # Stealth + visual
│   ├── run-cdp-profile-persist.bat   # Stealth + persistent session
│   ├── run-cdp-profile-screen-persist.bat  # Full power
│   ├── autoconnect.js                # CDP auto-connect helper
│   └── .gemini/settings.json         # Fallback MCP config
│
├── profiles/
│   ├── dom/
│   │   ├── system.md                 # Gemini system instructions (DOM mode)
│   │   └── oneshot.md                # One-shot variant (closes browser at end)
│   ├── visual/
│   │   ├── system.md
│   │   └── oneshot.md
│   ├── cdp/
│   │   ├── system.md
│   │   ├── oneshot.md
│   │   └── persistent.md
│   └── cdp-visual/
│       ├── system.md
│       ├── oneshot.md
│       └── persistent.md
│
├── .gemini/settings.json             # Main MCP config (set your cwd here)
├── GEMINI.md                         # Project-level Gemini instructions
├── LICENSE                           # ISC License
└── README.md

运行测试

# All tests that don't need network
npm run test:local

# Live network tests (Indeed + Google)
npm run test:remote

# Everything
npm run test:all

______________________________________________________________________

故障排除

“Chrome已在运行”/个人资料已锁定

# Use --kill-chrome
scripts\run-chrome-profile.bat --kill-chrome

# Or manually
taskkill /F /IM chrome.exe

Chrome 136+阻止默认用户数据目录上的自动化。始终使用专用配置文件或 ChromeForMCP 数据目录。

“Gmail说浏览器不安全”

你是通过Chromium连接的，而不是真正的Chrome。确保：

1. 启动前Chrome已完全关闭(--kill-chrome)
2. 发射响应显示 "persistent": true 以及您的个人资料路径
3. 如果没有，请重新启动Gemini并验证 .bat 输出 Using Chrome executable: ...

在Gemini中找不到MCP工具

• 运行任何 .bat 从任何目录--它们会自动修复 cwd
• 验证 .gemini/settings.json 有正确的 cwd
• 这 scripts/.gemini/settings.json 如果双子座开始，这是一个退路 scripts/

响应已截断/ retryWith 提示

这是正常工作的有效载荷预算。双子座会读 retryWith 提示并使用较低的参数重试。如果它继续发生，请切换到 light 轮廓：

browser.set_capture_profile({ profile: "light" })

性能缓慢

• 使用 run-dom-headless.bat 用于批量操作（无GUI=速度快3-4x）
• 避免 browser.extract_html --它返回完整的HTML并浪费令牌
• 使用 detail: "low" 在所有工具上，除非您特别需要更多

浏览器打开但忽略我的个人资料

检查 .bat 输出：

Using Chrome executable: C:\Program Files\Google\Chrome\Application\chrome.exe
Using Chrome profile: Profile 3

如果您看到其他配置文件或“未找到”，请编辑 .bat 并设置 MCP_PROFILE 明确地。

______________________________________________________________________

安全与隐私

路径限制

browser.evaluate （任意JS执行）是 默认情况下禁用。仅明确启用它： MCP_ALLOW_EVALUATE=true

files.read_text 和 files.write_text 仅限于：

• 阅读: Applied Jobs/, Auto/output/, Auto/logs/
• 写: Auto/output/, Auto/logs/

任何在这些路径之外读取或写入的尝试都会立即抛出。检查前先解析符号链接（防止遍历攻击）。

存储什么

什么东西从不存储

• ❌ 密码或凭据
• ❌ 信用卡或付款信息
• ❌ 浏览器历史
• ❌ 超出允许路径的个人文档

______________________________________________________________________

道德使用

此工具用于：

• 学习浏览器自动化和MCP开发
• 测试您自己的web应用程序
• 在您有权访问的网站上自动执行任务
• 合法的求职和申请工作流程

您负责：

• 关于 robots.txt 网站服务条款
• 遵守数据保护法规（GDPR、CCPA等）
• 限制您的请求速率以避免服务中断
• 未经授权，不得使用此功能绕过付费墙或访问控制

作者对误用不承担任何责任。负责任地使用。

______________________________________________________________________

这与微软官方有何不同 playwright-mcp

微软的 剧作家mcp 专注于 基于可访问性树的自动化 用于结构化环境中的测试开发。

使用Microsoft用于： CI/CD测试自动化，结构化可访问性驱动的工作流程 使用此功能： 在开放网络上运行的自主代理、作业申请自动化、反检测抓取

______________________________________________________________________

更新日志

v2.0.0（当前）

• 完整的架构重写：单片→ 11 模块化文件
• 71个MCP工具（23个）
• 捕获配置文件系统（轻/平衡/满），提高代币效率
• 硬280KB有效负载预算，具有优雅的截断和 retryWith 提示
• 多标签页管理器（列表、选择、关闭页面）
• 通过CDP实现稳定的A11y树快照 ax- 用户界面
• CDP原生点击/悬停/滚动后端DOMNodeId（处理Shadow DOM）
• 表单审核+智能填写+谷歌表单专家（6个工具）
• 会话导出/导入（cookie+本地存储持久性）
• 弹出、对话框、下载事件处理
• 滚动感知：获取状态、按增量滚动、滚动容器
• 通过CDP实现网络+控制台的可观察性
• 文件读取：文本文件+PDF提取
• 安全：路径允许强制执行，评估防护
• 18个测试套件（共2个）
• 7个配置文件启动器（原来是5个）：为CDP添加了持久变体
• GEMINI_CLI_MCP\_\*双环境变量支持GEMINI净化

v1.1.0版本

• 配置文件启动器系统（.bat文件）
• Chrome配置文件集成
• --kill-chrome 旗帜
• 单次模式，自动记录
• GEMINI_CLI_MCP\_\*环境变量别名
• browser.visual_snapshot 和 browser.click_at

v1.0.0

• 初始版本
• 带Playwright的基本MCP服务器
• Indeed+谷歌提取器
• DOM和视觉导航

______________________________________________________________________

贡献

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/your-feature)
3. 跑 npm run test:local 确认没有损坏
4. 承诺(git commit -m 'Add your feature')
5. 推送并打开拉取请求

______________________________________________________________________

许可证

ISC许可证--请参阅 许可证 文件。

______________________________________________________________________

致谢

• 剧作家 --浏览器自动化主干
• 模型上下文协议 --AI工具界面
• 微软剧作家mcp --A11y方法的灵感

______________________________________________________________________

支持

• 问题:
• 讨论: