BrowserTools MCP

BrowserTools MCP

如果你还在使用 1.x，请升级。 1.x 已停止支持，存在已知的严重漏洞（远程代码执行、未经身份验证即可访问捕获的数据），这些漏洞已在 2.0 中修复，且不会在 1.x 上修补。请参阅 SECURITY.md 和 MIGRATION.md。

让你的 AI 编码 Agent 看见浏览器中的内容。BrowserTools MCP 会将控制台输出、网络活动、屏幕截图和 Lighthouse 审计结果从你实际使用的 Chrome 会话（也就是已经登录你应用的会话）传输到任何兼容 MCP 的客户端：Cursor、Claude Code、Windsurf、Cline、Zed、Gemini CLI 等。

2.0 版是一次重写。 从三个进程精简为一个，不再有未经身份验证的本地服务，在凭据离开浏览器前将其清除，并新增了真正的测试套件。你从 1.x 升级而来？请阅读 MIGRATION.md。

---

为什么不使用基于 CDP 的服务

Chrome DevTools MCP 和 Playwright MCP 等工具会驱动一个全新、自动化的浏览器。这很适合编写测试，但不适合调试你正在查看的应用，因为从 Chrome 136 开始，浏览器会拒绝在默认配置文件上启用远程调试——而你的登录信息就保存在这个配置文件中。因此，在调试之前，你只能在临时配置文件中重新创建身份验证状态。

BrowserTools 通过 DevTools 扩展连接到你正在使用的会话。你可以保持登录状态，继续停留在当前页面，让 Agent 读取你看到的内容。它还会提供 Lighthouse 级别的性能、无障碍和 SEO 数据，而以自动化为先的服务无法做到这一点。

安装

需要两部分：一个 MCP 服务（一条命令即可）和一个 Chrome 扩展。

1. 将 MCP 客户端指向服务

{
  "mcpServers": {
    "browser-tools": {
      "command": "npx",
      "args": ["-y", "@agentdeskai/browser-tools-mcp@latest"]
    }
  }
}

在 Windows 上，如果客户端找不到 npx，请使用 "command": "cmd" 和 "args": ["/c", "npx", "-y", "@agentdeskai/browser-tools-mcp@latest"]。

需要 Node 22.19 或更高版本。使用 node --version 检查；如果你使用 nvm 或 asdf，请确保编辑器使用相同版本。

2. 加载 Chrome 扩展

1. 下载或克隆此仓库。
2. 打开 chrome://extensions 并启用开发者模式。
3. 选择加载已解压的扩展程序，然后选择 chrome-extension 目录。

至此，设置就完成了。无需启动第二个服务——MCP 服务会自行运行连接器。

3. 使用

在要检查的页面上打开 Chrome DevTools（F12）。打开 DevTools 后便会开始捕获；BrowserTools 面板仅用于设置和查看状态。然后向 Agent 提出类似*“检查控制台是否有错误”*或 *“对这个页面运行无障碍审计”*的问题。

无法正常工作？运行 npx @agentdeskai/browser-tools-mcp --doctor，它会准确指出缺少哪个部分。

若要实时查看捕获过程（检查全新安装时很有用），请使用 --verbose 启动连接器：

npx @agentdeskai/browser-tools-server --verbose

· console error tab 42 Uncaught TypeError: total is not a function
· network 500 POST tab 42 https://myapp.local/api/pay (1310ms)

不加此选项时，连接器只会报告连接和断开，因此无法区分正常工作的配置和没有响应的配置。

工具

工具	功能
getConsoleLogs	控制台输出，可按关键词筛选并分页
getConsoleErrors	错误级别的输出和未捕获的异常
getNetworkLogs	XHR/fetch 请求，包含状态、耗时和请求体
getNetworkErrors	仅显示失败的请求以及返回 4xx/5xx 的请求
getSelectedElement	Elements 面板中选中的元素
getPageInfo	浏览器当前所在页面
getConnectionStatus	扩展是否已连接，以及捕获数量
listBrowserTabs	已打开 DevTools 的标签页，通过连接 DevTools 的 tabId 标识
listTabs	chrome.tabs 返回的标签页（并非所有已打开的标签页），通过 chromeTabId 标识
readTab	读取 chromeTabId 对应标签页的标题、摘录和快照，无需调试器
navigateBrowser	在连接 DevTools 的标签页中加载 URL，不将其置于前台
navigateTab	在后台从 listTabs 加载 URL，仅限可见窗口
softClick / softType	执行不受信任的点击或输入。结果为 worked 或 needs a real gesture
takeScreenshot	截图以图像形式返回，并附带文件路径
refreshBrowser	重新加载正在检查的标签页
getBrowserStorage	localStorage、sessionStorage 和 cookie（值受访问限制）
wipeLogs	清除已捕获的遥测数据，以便进行干净的复现
runAccessibilityAudit	Lighthouse 无障碍审计
runPerformanceAudit	Lighthouse 性能审计，包含 Core Web Vitals
runSEOAudit	Lighthouse SEO 审计
runBestPracticesAudit	Lighthouse 最佳实践审计

此外还提供三个提示词：debuggerMode、auditMode 和 nextjsSeoAudit，为 Agent 提供系统化的工作流，避免每个工具列表中都出现一大段静态文本。

所有工具都声明了 MCP 输出架构，因此客户端接收的是结构化数据，而不是需要解析的散文；只读工具也会标注为只读，以便客户端安全地自动批准。

不使用 DevTools 的标签页

listTabs、readTab、navigateTab、softClick 和 softType 使用 chrome.tabs 和 chrome.scripting。它们不会连接调试器，因此不会显示调试横幅，也不会激活标签页或将窗口置于前台。

其他工具中的 chromeTabId 来自 listTabs。tabId 来自 listBrowserTabs。它们属于不同的 ID 空间。每个 ID 只能传给生成它的工具。

listTabs 会报告其返回的窗口中 chrome.tabs 返回的标签页。其他 Arc Spaces、Little Arc、固定的收藏夹、分屏伙伴和休眠标签页可能不会列出。无痕模式会跳过。这并不涵盖所有已打开的标签页。在 Arc 上完成测量之前，后台导航会留在可见窗口中。

弹出窗口开关必须处于开启状态。导航和软输入还需要为 browser-tools-mcp 设置 --allow-input，或为 browser-tools CLI 设置 --allow-actions。输入操作遵循与其他输入相同的来源规则。休眠标签页会被报告，但不会重新加载。软操作的结果为 worked 或 needs a real gesture，不会谎称失败的操作已成功。

同时处理多个标签页

每个已打开 DevTools 的标签页都会单独跟踪。遥测数据会归属于产生它的标签页，保留策略也按标签页分别应用，因此内容繁多的页面不会挤掉你关注的标签页的历史记录。

工具会作用于当前标签页——也就是你最近打开 DevTools 的标签页。标签页断开连接后重新连接，不会抢占该位置；此前这会导致截图捕获错误的页面。每个结果都会报告其来源的 tabId 和 url，以及 otherTabs，因此如果回答针对了错误的标签页，这一点会显而易见，而非悄无声息。若要指定标签页，请调用 listBrowserTabs 并将其 tabId 传给任意工具；传入 allTabs: true 可读取所有标签页的数据。

大型数据不会占用上下文窗口

完整历史记录的数据会以 MCP 资源的形式提供，而不是直接嵌入；工具会通过 resource_link 链接到这些资源，让你的 Agent 仅在决定需要时才获取：

资源	内容
browser-tools://console/{tabId|all}	所有控制台条目，没有单次调用预算限制
browser-tools://network/{tabId|all}	所有捕获的请求，包括请求体
browser-tools://har/{tabId|all}	同一份流量数据，以 HAR 1.2 文件形式提供
browser-tools://screenshot/{name}	你之前捕获的截图
browser-tools://audit/{reportId}	摘要所依据的完整 Lighthouse 结果

如果读取因截断而提前结束，日志工具会附加一个链接；网络读取始终会提供 HAR；截图始终会链接到存储的图片，这是查看过大而无法内嵌的截图的唯一方式。最近 20 份完整 Lighthouse 报告会保存在截图目录下的 audits/ 中。

控制响应大小

日志数据通常是导致上下文窗口溢出的原因。每个读取工具都接受 limit 和 offset，日志工具还接受关键词筛选条件：

getConsoleErrors({ keywords: ["hydration"], limit: 20 })
getNetworkLogs({ urlKeywords: ["/api/"], bodyKeywords: ["quota"], limit: 10 })

结果按时间从新到旧返回，并且始终会同时报告 total 和 returned，以便 Agent 知道当前看到的内容是否完整。

隐私与安全

此工具会捕获浏览器看到的所有内容，因此会谨慎处理这些数据：

• 仅限回环地址。 连接器绑定到 127.0.0.1，并拒绝非回环地址。在 1.x 中，它绑定到 0.0.0.0，网络上的任何人都能访问。
• 扩展程序不会离开回环地址范围。 1.x 会扫描专用网络地址范围，并采用任何以已知字符串响应的主机——这意味着共享 Wi-Fi 上的任何人都可能收到你的日志和截图。这项扫描已被移除。
• 需要身份验证。 HTTP API 需要每次运行对应的持有者令牌。URL 中的令牌会被拒绝。扩展程序 WebSocket 也需要相同的令牌；扩展程序会从仅响应浏览器扩展程序来源的回环配对路由获取令牌，而 /.identity 不会泄露令牌。传入 --extension-id，即可只接受指定扩展程序，不接受其他扩展程序。
• 凭据会在传入时被清理：Authorization、Cookie 等标头，以及在捕获字符串任何位置发现的 JWT、云服务密钥和供应商令牌，都会变成 [REDACTED]。
• 默认情况下，标头会按传输方向关闭；除非明确请求，否则不会提供存储值。
• Cookie 访问是你从面板授予的可选权限，不是扩展程序默认持有的权限。
• 调试器横幅会一直显示。 Chrome 的“已开始调试此浏览器”警告是一项安全控制。它是有意保留的，本项目绝不会将其隐藏。不附加调试器的捕获方式不会触发横幅；但这并不能用来关闭横幅。
• 审计不会访问你的内部网络。 审计接受一个 url，而调用方可能是正在读取不可信页面的模型。绝不会审计链路本地地址和云元数据地址。只有在本地页面或专用网络页面已在已连接的标签页中打开（或通过 --audit-allow-origin 加入允许列表）时，才会对其进行审计；审计浏览器发出的每个请求——包括重定向和子资源请求——也会在发生时再次检查。本地页面只能加载已在标签页中打开或已加入允许列表的本地来源；因此，如果你的应用会调用另一个本地端口上的 API，也要打开该端口或将其加入允许列表。审计会直接连接，不会通过系统代理。在使用会隐藏域名实际去向的假 IP 代理（Clash、sing-box、Surge）时，除非传入 --audit-allow-private-network，否则会拒绝审计；详见 SECURITY.md。

请按照 SECURITY.md 报告漏洞。

配置

标志或对应的 BROWSER_TOOLS_* 环境变量：

标志	用途
--port <n>	连接器端口（默认值为 3025）
--screenshot-dir <path>	截图的写入位置
--only <a,b>	仅公开这些工具，适用于 MCP 和本地 API
--exclude <a,b>	隐藏这些工具，适用于 MCP 和本地 API
--allow-actions	允许本地 API 重新加载、捕获、清除数据、更改设置和选择标签页。否则，需要在 BrowserTools 面板中确认。嵌入连接器的进程中的 MCP 工具不受此限制
--extension-id <id>	仅允许此扩展程序配对和连接
--doctor	检查设置并退出
--verbose	收到每条捕获记录时将其打印出来
--host <addr>	要绑定的环回地址（默认值为 127.0.0.1）
--connect <url>	连接到已在其他位置运行的连接器
--token <t>	与 --connect 一起使用的身份验证令牌
--no-redact	禁用凭据清理（不推荐）
--audit-allow-origin <o,o>	审计可在没有打开标签页时访问或加载的环回／专用网络来源
--audit-allow-private-network	允许审计访问任何环回／专用网络地址，但不包括审计自身的端口（不推荐）；在假 IP 代理后方时也需要此选项

若要让多个 MCP 客户端共享一个浏览器会话，只需使用 npx @agentdeskai/browser-tools-server 启动一次连接器，所有客户端都会自动连接到它。本地 API 使用该进程的 --only、--exclude、--allow-actions 和 --extension-id。已连接客户端的 --only / --exclude 仍会对该客户端隐藏工具。

已知限制

• 网络捕获会在 DevTools 打开时开始。此前已完成的请求不会被记录——重新加载页面即可捕获完整的页面加载过程。
• 截图受字节数上限限制（screenshotMaxBytes，默认值为 3 MB）。如果捕获结果超出上限，会重新编码为 JPEG；如果仍然过大，则会缩小尺寸。高 DPI 显示器上密集内容的视口截图可能会超过 13 MB，这超出了模型上下文的承载能力，也超过了较新 MCP 标准输入／输出传输所施加的读取缓冲区限制。如果图像仍无法容纳，工具会将其写入磁盘，并返回路径而不是内嵌图像。
• 默认情况下，控制台捕获使用 DevTools 协议，这会让 Chrome 显示“此浏览器已开始调试”横幅。该横幅是有意显示的，不会被隐藏。将面板的捕获模式切换为 Wrap page console，即可在不连接调试器的情况下捕获控制台。
• Firefox 尚未经过验证。 此扩展采用跨浏览器编写方式——包含 browser/chrome 垫片、browser_specific_settings，以及无需 chrome.debugger 的捕获模式——但从未在 Firefox 中加载过，测试套件也未涵盖 Firefox。尤其是截图通过 DevTools 协议实现，因此无法在 Firefox 中使用。在有人实际运行验证之前，请将 Firefox 视为不受支持；欢迎反馈验证结果。
• 审计会启动独立浏览器，耗时最长可达一分钟。任何基于 Chromium 的浏览器都可使用，包括 Chrome、Chromium、Brave、Edge、Vivaldi、Opera 或 Arc；--doctor 会报告将使用哪个浏览器。设置 CHROME_PATH 可覆盖此选项。Arc 仅尽力提供支持，且尚未在无头模式下验证。

开发

npm install
npm run build
npm test           # unit + integration, no browser required
npm run test:e2e   # real Chromium with the extension loaded (headless)

npm test 几秒钟即可运行完毕。端到端测试套件会启动安装了扩展程序的 Chromium，驱动测试页面，并验证完整的捕获流程。测试以无头模式运行；设置 HEADED=1 可打开可见窗口。请先运行 npx playwright install chromium。

许可证

MIT