CI Version Tests Node License

turbo-browser-mcp是一个基于 Playwright 的 Model Context Protocol (MCP) 服务器,旨在减少浏览器自动化中的 LLM token 浪费和多轮延迟。它将 25-33 个细粒度浏览器原语整合为10 个批处理工具具备增量 DOM 快照、单轮 React/Shadow DOM/iframe 表单预填、直接磁盘文件上传(上下文中无 Base64)、并行标签页会话、网络阻断预设,以及默认的人工介入 Submit 保护。


性能与 Token 记分卡一览

以下所有数据均来自benchmarks/benchmark.mjs(npm run benchmark)在本地以无头 Chromium 运行,并使用精确的 OpenAIo200k_base分词(tiktoken 0.14.0):

能力 典型基线 turbo-browser-mcp 速度 / 轮次提升 Token 节省(o200k_base)
密集 UI 快照(140 按钮 SaaS 控制台) 18,654tok HTML /3,568tok 完整 ARIA 1,135tok紧凑(28 ms) 1调用 93.9%对比 HTML(68.2%对比 ARIA)
点击后增量快照(onlyChanged: true) 3,582tok 完整 ARIA 重新扫描 56tok变更行(18 ms) 1调用 98.4%对比 ARIA(99.7%对比 HTML)
10 字段复杂表单 + 快照(smart_fill_form) 11轮(574 ms,12,197dir /72,614累计 tok) 1轮(82 ms,811tok) 7x更快,11 -> 1轮 93.4%直接 /98.9%累计
48 KiB PDF 上传(49,152字节) 44,728tok 内联 Base64 工具参数 85tok磁盘路径(68 ms) 零 Base64 生成 99.8%节省
6 步交互式 UI 流程(batch_actions) 6轮(411 ms,955dir /3,162累计 tok) 1轮(357 ms,406tok) 1.15x更快,6 -> 1轮 57.5%直接 /87.2%累计
并发打开 6 个标签页(open_many) 6轮 顺序(998 ms) 1轮批处理(420 ms) 2.38x更快,6x更少轮次 5更少提示重放
重媒体加载(preset: "turbo",304 KiB资源) 252 ms,9媒体请求(304 KiB) 165 ms,0媒体请求(0 KiB) 1.53x更快 100%媒体带宽减少
文章 Markdown 抓取(extract_clean_text) 3,595tok 原始 HTML(10,844字符) 156tok干净 Markdown(641字符) 干净的阅读器输出 95.7%节省
诊断分诊(page_diagnostics仅错误) 3,460tok 未过滤(32req /26console) 601tok默认错误(2req /6console) 零噪音滚动 82.6%节省
静态 MCP 工具 Schema(每轮开销) 3,917tok Playwright /6,737tok DevTools 3,010tok精简(3,314完整含注解) 10工具 对比25/33 23.2%对比 Playwright /55.3%对比 DevTools

关于延迟与 LLM 推理轮次的说明:消除10在 10 字段表单上的往返可同时节省7x浏览器执行时间(574 ms -> 82 ms)以及10独立的 LLM 推理往返(2-5s智能体循环中每轮)外加~71,800重放的历史 token。


浏览器智能体为何停滞:并排工作流

标准 MCP 服务器为每次快照、字段填写、<select>选择、上传和验证检查都收取一次 LLM 往返。每一轮都会将不断增长的对话历史重新发送回模型。

sequenceDiagram
    autonumber
    participant Agent as LLM Agent
    participant Std as Standard MCP (Playwright / DevTools)
    participant Turbo as turbo-browser-mcp

    Note over Agent,Std: Standard MCP (12+ LLM turns, full ARIA tree + history replay each step)
    Agent->>Std: 1. snapshot() -> full ARIA (~3,568 tok)
    loop Repeats 10+ times across fields, selects, checkboxes, upload
        Agent->>Std: fill / select_option / click
        Std-->>Agent: full ARIA or confirmation re-added to history
    end
    Agent->>Std: 12. upload inline or click chooser

    Note over Agent,Turbo: turbo-browser-mcp (2 LLM turns total, delta & inline snapshot)
    Agent->>Turbo: 1. inspect_compact(mode: "forms") -> compact refs (1,135 tok)
    Agent->>Turbo: 2. smart_fill_form(fields: [...10 fields + disk PDF...], returnSnapshot: true)
    Turbo-->>Agent: Filled 10 fields + guarded before Submit + inline snapshot (811 tok)
加载

什么turbo-browser-mcp支持

1. 连接与会话隔离

  • 4 种连接模式(--mode auto|cdp|persistent|launch):
    • auto(默认):探测--cdp http://127.0.0.1:9222首先,智能体可以复用现有的已登录浏览器会话,然后回退到启动 Chromium。
    • cdp:直接附加到正在运行的 Chromium/Chrome/Edge 远程调试端口。
    • persistent:使用可复用的--user-data-dir配置文件跨多次运行启动。
    • launch:启动一个干净的浏览器会话(--headless默认,或--headed)。
  • 自动二进制发现(src/playwright-loader.mjs):检查playwright-core在 Windows、macOS 和 Linux 上的缓存版本、Google Chrome、Microsoft Edge、Brave 和 Chromium 的系统安装,或显式指定的--executable <path>。
  • 按标签页隔离(tabs_batch):在命名的isolatedContext沙箱中打开标签页,具有独立的 cookie 和存储,批量打开最多 10 个并发 URL(open_many),激活、重新加载、前进back/forward,resize视口,并模拟colorScheme,media,reducedMotion,contrast,forcedColors,或自定义userAgent。

2. DOM、Iframe 与 Shadow DOM 检查(inspect_compact)

  • 快照模式: interactive,forms,article,以及all。
  • 跨边界遍历:展平主框架 DOM、子 iframe(includeFrames,frameIdx)以及开放的 Shadow DOM。注入一个初始化脚本,挂钩Element.prototype.attachShadow(WeakMap+WeakRef/FinalizationRegistry+window.__tbmGetShadowRoot)以保持初始化后关闭的 Shadow root 可检查且受保护,遍历<slot> assignedNodes({ flatten: true }),并支持表单关联自定义元素。
  • Token 控制: onlyChanged: true仅输出自上次快照以来新增或更改的元素;query按正则表达式或子字符串过滤;boxes: true仅在需要时添加[box=x,y,w,h];maxChars限制负载大小;savePath将完整输出写入磁盘。

3. 单轮智能表单引擎(smart_fill_form)

在一次 MCP 调用中预填整个表单,同时在受控输入之间刷新微任务和宏任务:

  • 标准与框架输入:text、email、password、number、date、textarea、<input type="range">、复选框、单选组(check,not,overwrite)。通过原生属性 setter 和合成事件触发 React 受控状态更新。
  • 选择器与自定义控件: <select>和<select multiple>(option/values)、ARIA 组合框、ARIA 开关、contenteditable富文本编辑器,以及 Gmail 撰写对话框(gmail: { to, subject, body })。
  • 框架与通配符定位:通过以下方式定位特定 iframeframeIdx,或设置all: true以跨框架填充匹配的控件。
  • 直接磁盘上传:将file或files路径直接传递给 PlaywrightsetInputFiles,而无需将二进制文件或 Base64 字符串加载到 LLM 上下文中。
  • 原子验证:传递returnSnapshot: true以在同一工具响应中检查更新后的表单状态。

4. 16 种交互操作与多步链式调用(act_fast,batch_actions)

  • act_fast操作: click,dblclick,hover,focus,clear,fill,type(slowly,delayMs,submit),select,check,uncheck,drag,drop(file,files,或自定义 MIMEdropData),press(key+modifiers:Alt,Control,ControlOrMeta,Meta,Shift),scroll(dx,dy),wait(ms,state,loadState,text,textGone,url),以及upload。
  • 定位选项:紧凑[eN] ref,CSSselector,可见text,label,或视口(x, y)坐标,配合button(left,right,middle)和frameIdx。
  • batch_actions:运行一个有序的 DOM 操作列表和嵌套的smart_fill_form在一次 MCP 调用中完成这些步骤,如果被 Submit guard 阻止则安全停止,或者可选地在步骤出错时继续(continueOnError)。

5. 干净提取、评估与媒体捕获(extract_clean_text,evaluate_js,capture_page)

  • extract_clean_text:从 main/article 容器和 iframe 中提取可读的纯文本或紧凑的 Markdown(format: "text" | "markdown"),并去除 script 和 style 噪声。
  • evaluate_js:在任意 frame 中运行 JS 表达式或(el, arg)元素函数(frameIdx),结果以 JSON 序列化,并可选savePath导出。
  • capture_page:整页或元素范围的截图(png或jpeg配合quality、css或device缩放,可选returnImage)以及 PDF 生成,保存到受限的savePath。

6. 网络拦截、存储状态与诊断(network_session,page_diagnostics)

  • network_session预设: turbo,no-images,no-media,以及clean(解除全部拦截),同时支持自定义blockResources和blockUrls模式。
  • 会话与存储管理:读取/写入/清除浏览器cookies,localStorage/sessionStorage,以及导出或重新加载完整的 PlaywrightstorageStateJSON 文件(saveStorageStatePath,loadStorageStatePath)。
  • page_diagnostics:默认仅显示错误(level: "errors",statusFilter: "errors"),以干净地暴露失败而不淹没上下文,同时支持all,includeStatic,urlFilter,深度请求/响应检查(reqId+part),已完成的下载,以及对话框自动处理(dialogPolicy:accept/dismiss)。

可复现基准测试(npm run benchmark)

在安装 Chromium 和 Playwright 的情况下自行运行基准测试套件:

npm run benchmark

环境与方法:通过以下方式运行无头 Chromiumplaywright-core,使用 Python 统计精确的 OpenAIo200k_basetokentiktoken(approx-bpe在tiktoken不可用时的回退方案)。累计工作流 token 模拟跨 $N$ 个连续轮次的标准聊天历史重放:$\sum_{i=1}^{N} (N - i + 1) \cdot T_i$,外加一个一次性基线,其中第一轮在行动前捕获上下文。

1. 快照与阅读器提取(字符数与精确o200k_basetoken 数)

场景 原始 HTML 完整 Playwright ARIA turbo-browser-mcp输出 相比 ARIA 节省 相比 HTML 节省
140 按钮 SaaS 控制台(inspect_compact) 61,010字符(18,654tok) 12,771字符(3,568tok) 3,968字符(1,135tok) 68.2% 93.9%
点击后增量(onlyChanged: true) 61,010字符(18,654tok) 12,825字符(3,582tok) 168字符(56tok) 98.4% 99.7%
文章 Markdown 提取(extract_clean_text) 10,844字符(3,595tok) n/a 641字符(156tok) n/a 95.7%
诊断过滤(32请求,26控制台日志) 9,651字符(3,460tok,all) n/a 1,761字符(601tok,errors) n/a 82.6%

2. 多轮表单、工作流、上传与网络速度

场景 逐步基线 turbo-browser-mcp 执行加速 token 节省
10 字段复杂表单 + 验证(smart_fill_form) 11轮,574 ms,12,197直接 /72,614累计 tok 1轮,82 ms,811tok(filled=10) 7x更快 93.4%直接 /98.9%累计
48 KiB PDF 上传(49,152字节,通过file) 65,679字符(44,728tok)Base64 载荷 263字符(85tok)磁盘路径(68 ms) 零 LLM Base64 编码 99.8%
6 步 UI 流程(batch_actions) 6轮,411 ms,955直接 /3,162累计 tok 1轮,357 ms,406tok 1.15x更快 57.5%直接 /87.2%累计
打开 6 个标签页(tabs_batch open_many,60 msTTFB) 6轮顺序(998 ms) 1轮批量(420 ms) 2.38x更快(6 -> 1轮) 消除5轮
大量媒体加载(8x32 KiB图片 +48 KiB字体) 252 ms,9媒体命中(304 KiB) 165 ms,0媒体命中(0 KiB) 1.53x更快 100%媒体节省

3. 静态 MCP 工具定义占用空间

以磁盘上已安装的 MCP JSON schema 为基准测量(紧凑参数 schema,不含annotations):

MCP 服务器 工具数量 紧凑 schema 字符数 精确o200k_baseToken 数 节省比例(turbo-browser-mcp
turbo-browser-mcp 10(14,186完整 /12,796紧凑) 12,796 3,010(3,314完整含注解) 基线(10工具)
@playwright/mcp 25 18,457 3,917 23.2%更少的静态 token
chrome-devtools-mcp 33 30,252 6,737 55.3%更少的静态 token

对比@playwright/mcp与chrome-devtools-mcp

特性 turbo-browser-mcp @playwright/mcp chrome-devtools-mcp
工具面规模 10 个批处理工具 25 个细粒度工具 33 个细粒度工具
增量快照(onlyChanged) 内置 每次快照完整树 每次快照完整树
闭合 Shadow DOM 钩子 初始化后attachShadow钩子 +<slot>扁平化 开放 Shadow DOM CDP / 标准 DOM 访问
单次调用智能表单 + contenteditable 支持(React、Shadow DOM、iframe、Gmail、范围) 多轮填充 + 单独的选择调用 基础fill_form
磁盘文件上传(零 Base64) 原生file/files路径位于smart_fill_form&act_fast 专用browser_file_upload轮次 专用upload_file轮次
默认人在回路提交守卫 支持(allowSubmit=false、表单/iframe/Enter 钩子) 否 否
并行open_many+isolatedContext 单次批处理调用 单独的串行标签页调用 单独的页面调用
单次调用turbo媒体拦截器 内置(turbo,no-images,no-media) 手动 JS / 路由 网络模拟
性能 / 堆分析 未包含 未包含 Trace、Lighthouse、堆快照

何时需要同时保留 Chrome DevTools MCPturbo-browser-mcp: chrome-devtools-mcp提供 Lighthouse 审计、性能 trace 分析、CSS 计算样式面板和 V8 堆快照。turbo-browser-mcp专注于快速多步 UI 自动化、表单和抓取,token 开销极小。

工具对等映射表

能力 turbo-browser-mcp @playwright/mcp chrome-devtools-mcp
多标签页打开、列出、切换、调整大小、模拟 tabs_batch browser_tabs,browser_navigate,browser_resize,…… new_page,list_pages,select_page,resize_page,……
DOM / 无障碍检查 inspect_compact browser_snapshot take_snapshot
多字段表单与上传 smart_fill_form browser_fill_form+browser_select_option+browser_file_upload fill_form+upload_file
点击、输入、拖拽、按键、滚动、等待 act_fast browser_click,browser_type,browser_drag,…… click,type_text,drag,press_key,wait_for
多步顺序宏 batch_actions browser_run_code_unsafe或 N 次工具调用 N 次单独工具调用
干净文章提取 extract_clean_text browser_evaluate自定义 JS evaluate_script自定义 JS
Frame/元素 JS 求值 evaluate_js browser_evaluate evaluate_script
错误、网络与控制台排查 page_diagnostics browser_console_messages,browser_network_requests list_console_messages,list_network_requests,……
截图与 PDF 导出 capture_page browser_take_screenshot take_screenshot
拦截预设、Cookie 与存储 network_session browser_evaluate+ 上下文配置 部分通过evaluate_script/emulate

安全:人在回路提交守卫与路径限制

  1. 人在回路提交守卫(allowSubmit=false默认开启):
    • smart_fill_form(stopBeforeSubmit: true),act_fast、以及batch_actions检查匹配元素、W3C AccName 标签(isSafeSubmitter)、隐式 HTML 表单 Enter 提交、组合键(Shift+Enter,Enter+Shift)、HTMLFormElement.prototype.submit/requestSubmit,以及同源 iframecontentWindow/contentDocument代理。
    • 类似以下行为的最终操作Submit,Publish,Send,Post,Apply,Confirm,或支付触发会被阻止,除非allowSubmit: true被显式传入或--allow-submit在启动时启用。
    • 权衡:已打开的 CDP 标签页上预先存在的封闭 Shadow root(在初始化脚本运行之前附加的),或严格的跨源沙箱 iframe,会回退到 Playwright 的 frame 句柄、坐标操作和键盘输入。
  2. 工作区路径限制(TURBO_BROWSER_SAVE_ROOT):
    • 文件输出(savePath,saveStorageStatePath)和状态输入(loadStorageStatePath)被严格限制在当前工作目录或TURBO_BROWSER_SAVE_ROOT。
    • 词法检查、lstatSync/readlinkSync符号链接验证和realpathSync校验会在读取或写入之前阻止..路径遍历、UNC 网络路径、悬空符号链接、循环符号链接和 Windows junction。

全部 10 个工具参考

工具 用途 关键参数
tabs_batch 有序的标签页与浏览器生命周期 operations[](list,open,open_many,navigate,activate,resize,emulate,reload,back,forward,close,close_browser),isolatedContext,concurrency(1-10)
inspect_compact 受 token 上限约束的元素/表单/文章快照 mode(interactive,forms,article,all),onlyChanged,query,boxes,maxChars,includeFrames,savePath
smart_fill_form 批量表单、编辑器与磁盘文件预填 fields[](ref,selector,value,option,values,check,not,keys,file,files,frameIdx,all),gmail,overwrite,stopBeforeSubmit,returnSnapshot
act_fast 单个定向页面操作 action(16个操作),ref/selector/text/label/(x, y),modifiers,dropData,allowSubmit,returnSnapshot
batch_actions 有序的操作链 + 表单步骤 steps[],continueOnError,allowSubmit,returnSnapshot,snapshotMaxChars
extract_clean_text 纯文本或紧凑 Markdown 阅读器 format(text,markdown),selector,includeFrames,maxChars,savePath
evaluate_js 限定作用域的 JS 表达式或(el, arg)调用 expression,arg,frameIdx,ref/selector/text,savePath
page_diagnostics 控制台、网络、下载与对话框 level(errors,all),statusFilter(errors,all),includeStatic,urlFilter,reqId,part,dialogPolicy,clear,savePath
capture_page PNG/JPEG 截图与 PDF 导出 mode(screenshot,pdf),type,quality,fullPage,scale(css,device),ref/selector/text,returnImage,savePath
network_session 资源拦截器、cookie 与存储 preset(turbo,no-images,no-media,clean),blockResources,blockUrls,cookieAction,storageAction,loadStorageStatePath,saveStorageStatePath

复制粘贴 JSON 示例

1. 用磁盘上的 PDF 填充一个 10 字段表单,并在 1 轮内检查结果

{
  "name": "smart_fill_form",
  "arguments": {
    "fields": [
      { "selector": "#full_name", "value": "Alex Nguyen" },
      { "selector": "#email", "value": "alex@example.com" },
      { "selector": "#country", "option": "United States" },
      { "selector": "#skills", "values": ["TypeScript", "Playwright"] },
      { "selector": "#agree_terms", "check": true },
      { "selector": "#resume_pdf", "file": "./assets/resume.pdf" }
    ],
    "stopBeforeSubmit": true,
    "returnSnapshot": true
  }
}

2. 打开模态框后只读取发生变化的控件(onlyChanged)

{
  "name": "inspect_compact",
  "arguments": {
    "mode": "interactive",
    "onlyChanged": true,
    "maxChars": 3000
  }
}

3. 在隔离的上下文中并发打开标签页,并通过以下方式加速加载turbo

{
  "name": "tabs_batch",
  "arguments": {
    "operations": [
      { "action": "open", "url": "https://example.com/app", "isolatedContext": "acct-a" },
      { "action": "open_many", "urls": ["https://example.com/docs", "https://example.com/pricing"], "concurrency": 4 }
    ]
  }
}

快速开始

安装并检查环境

git clone https://github.com/Tthanh2k6/turbo-browser-mcp.git
cd turbo-browser-mcp
npm install
npm run doctor

如果你需要 Playwright 自带的 Chromium(或者没有安装系统 Chrome/Edge/Brave):

npx playwright-core install chromium

MCP 客户端配置(Claude Code、Cursor、Antigravity、Codex)

使用本地克隆:

{
  "mcpServers": {
    "turbo-browser": {
      "command": "node",
      "args": ["/absolute/path/to/turbo-browser-mcp/src/index.mjs"],
      "env": {
        "TURBO_BROWSER_SAVE_ROOT": "/absolute/path/to/allowed/workspace"
      }
    }
  }
}

使用npx/ 二进制入口:

{
  "mcpServers": {
    "turbo-browser": {
      "command": "npx",
      "args": ["-y", "turbo-browser-mcp"]
    }
  }
}

CLI 选项与环境变量

CLI 标志 环境变量 默认值 描述
--mode <auto|cdp|persistent|launch> TURBO_BROWSER_MODE auto 连接策略(cdp优先,然后启动于auto)
--cdp <url> TURBO_BROWSER_CDP_URL http://127.0.0.1:9222 Chrome DevTools Protocol HTTP 端点
--user-data-dir <path> TURBO_BROWSER_USER_DATA_DIR "" 持久化配置文件目录路径
--executable <path> - 自动检测 自定义 Chromium、Chrome、Edge 或 Brave 可执行文件
--timeout <ms> TURBO_BROWSER_TIMEOUT_MS 15000 默认 Playwright 操作/导航超时时间(毫秒)
--headless/--headed TURBO_BROWSER_HEADLESS true(无头) 以无头模式或可见浏览器窗口运行("false"为有头模式)
--allow-submit - false 禁用默认的提交/发布确认保护
--doctor - - 以 JSON 形式打印 Node、Playwright、Chromium 和 CDP 诊断信息
--bridge TURBO_BROWSER_BRIDGE_PORT 9224 为 Chrome 144+ 启动/验证持久化 CDP Keep-Alive Bridge 守护进程DevToolsActivePort(批准一次,之后可无限次 AFK 重连)
--launch-chrome - ~/.turbo-browser-mcp/chrome-profile 使用专用配置文件和--remote-debugging-port=9222(0不再有批准提示)启动 Chrome
--version/-v - - 打印服务器版本(0.4.0)
--help/-h - - 打印 CLI 用法摘要
- TURBO_BROWSER_SAVE_ROOT process.cwd() 限制savePath和storageState文件的根目录
- PLAYWRIGHT_CORE_PATH 自动解析 显式指定路径到playwright-core/index.mjs

无人值守过夜 / AFK 自动化(消除 Chrome 144+ 批准提示)

在 Chrome 136+/144+ 中,在默认chrome://inspect/#remote-debugging上启用User Data目录会在DevToolsActivePort中暴露一个 WebSocket,每当有新的 WebSocket 客户端连接时,它会显示一个"允许远程调试?"提示。turbo-browser-mcp提供两种内置方案,让过夜 AFK 多智能体运行永远不会卡在提示上:

  1. 自动 CDP Keep-Alive Bridge 守护进程(npm run bridge/--bridge,在DevToolsActivePort时自动启用):
    • 生成一个分离的后台多路复用器(src/cdp-bridge.mjs在http://127.0.0.1:9224上),它持有一个持久的上游 WebSocket与 Chrome 保持无限期连接,并拦截Browser.close,因此下游脚本永远不会终止你的浏览器。
    • 你在启动会话时点击一次允许;之后,任意数量的 MCP 服务器、CLI 脚本或子智能体都可以整夜连接和断开,0 额外提示。
  2. 零提示专用配置文件启动器(npm run launch-chrome/--launch-chrome):
    • 使用--remote-debugging-port=9222和专用--user-data-dir(~/.turbo-browser-mcp/chrome-profile)启动 Chrome,Chrome 会暴露标准 HTTP/WS CDP,即使首次连接也有 0 个确认对话框。

验证

npm 测试            #86 个测试套件中共 407 个测试通过(test/*.test.mjs 下有 26 个测试文件)
npm run doctor      #Node、Playwright、Chromium 和 CDP 的环境检查
npm run bridge      #启动/验证持久化 CDP Keep-Alive Bridge 守护进程
npm run benchmark   #本地 Chromium 速度与精确 o200k_base token 基准测试

在 GitHub Actions(ubuntu-latest)上自动测试,覆盖Node 20和Node 22.

License

MIT