BrowserTools MCP Server

什么是 BrowserTools MCP Server？

BrowserTools MCP Server 是 AgentDeskAI 推出的浏览器 MCP（browser MCP）服务器，可将你真实、已登录的 Chrome 会话中的控制台日志、网络请求、截图和 Lighthouse 审计结果实时传给 Cursor、Claude Code、Windsurf 等 AI 编程助手。

它通过一个 Chrome DevTools 扩展工作，而不是另外启动一个自动化浏览器，因此 AI 助手看到的就是你正在调试的页面，并保留你现有的登录状态。2.0 版本（npm 包 @agentdeskai/browser-tools-mcp，撰写本文时为 2.0.2）是一次彻底重写：从三个进程合并为一个，连接器仅监听本地回环地址并需要认证，并会清除凭据信息。项目基于 MIT 许可证开源。

如何使用 BrowserTools MCP Server？

安装分为两部分：MCP 服务器（一条 npx 命令）和 Chrome 扩展。

前置条件： Node.js 22.19 或更高版本（用 node --version 检查；如果使用 nvm 或 asdf，请确保编辑器继承的是同一版本），以及 Google Chrome 或其他基于 Chromium 的浏览器。无需 API 密钥。

1. 将 MCP 服务器添加到客户端

以下是 README 中的配置，适用于任何支持标准 mcpServers 配置块的客户端：

{
  "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"]。

2. 加载 Chrome 扩展

1. 下载或克隆 browser-tools-mcp 仓库。
2. 打开 chrome://extensions 并开启 Developer mode（开发者模式）。
3. 点击 Load unpacked（加载已解压的扩展程序），选择 chrome-extension 目录。

无需再启动第二个服务器。在 2.0 中，MCP 服务器会自行运行连接器。

3. 打开 DevTools 并向 AI 助手提问

在要检查的页面上打开 Chrome DevTools（F12）。DevTools 一打开就开始采集；BrowserTools 面板仅用于设置和查看状态。然后可以这样提问：“check the console for errors”（检查控制台中的错误）。

Claude Code

用 Claude Code CLI 注册同样的命令：

claude mcp add browser-tools -- npx -y @agentdeskai/browser-tools-mcp@latest

Cursor

将上面的 JSON 配置块添加到 Cursor 的 MCP 配置中（项目内为 .cursor/mcp.json，全局为 ~/.cursor/mcp.json），然后重新加载 Cursor。

Windsurf

将同样的 mcpServers 配置块添加到 Windsurf 的 MCP 配置中，并刷新服务器列表。

BrowserTools MCP Server 的主要功能

• 使用你的真实会话： 通过 DevTools 扩展接入，你可以保持登录状态并停留在原来的页面。README 指出，自 Chrome 136 起，浏览器拒绝对默认配置文件进行远程调试，这也是基于 CDP 的服务器需要使用全新配置文件的原因。
• 控制台与网络采集： 控制台输出、未捕获的异常，以及包含状态、耗时和请求/响应体的 XHR/fetch 请求。
• 截图以图片形式返回，同时附带保存路径，并设有字节上限（默认 3 MB），确保截图能放进模型上下文。
• Lighthouse 审计： 覆盖无障碍、性能（含 Core Web Vitals）、SEO 和最佳实践。
• 支持多标签页： 每个打开了 DevTools 的标签页都会单独跟踪，每条结果都会注明来源的 tabId 和 url。
• 节省上下文的输出： 支持 limit/offset 分页、关键词过滤、结构化输出 schema，以及用于大体量数据的 MCP 资源（包括 HAR 1.2 导出）。
• 默认注重隐私： 连接器仅监听本地回环地址，每次运行使用独立的认证令牌，并会脱敏 Authorization/Cookie 请求头、JWT 和云服务密钥。
• 可配置： 提供 --port（默认 3025）、--screenshot-dir、--only、--exclude、--doctor 等参数，或对应的 BROWSER_TOOLS_* 环境变量。

BrowserTools MCP Server 工具

这些 browser tools MCP 工具分为四组：

• 控制台日志： getConsoleLogs 和 getConsoleErrors 返回控制台输出和错误，可用 keywords、limit 和 offset 过滤。
• 网络： getNetworkLogs 和 getNetworkErrors 返回全部请求或仅返回失败及 4xx/5xx 的请求，可用 urlKeywords 和 bodyKeywords 过滤。
• 页面与浏览器状态： getSelectedElement（Elements 面板中选中的元素）、getPageInfo、getConnectionStatus、listBrowserTabs、takeScreenshot、refreshBrowser、getBrowserStorage（localStorage、sessionStorage 和 cookie，除非明确请求，否则不返回具体值）以及 wipeLogs。
• 审计： runAccessibilityAudit、runPerformanceAudit、runSEOAudit 和 runBestPracticesAudit 会在单独的无头浏览器中运行 Lighthouse。

另有三个 MCP 提示词（prompt）：debuggerMode、auditMode 和 nextjsSeoAudit，为 AI 助手提供分步骤的调试或审计流程。在 1.x 中它们是工具。

BrowserTools MCP Server 的使用场景

• 无需复制粘贴即可调试前端错误： “检查这个页面控制台里的错误，并修复抛出错误的组件。”
• 排查失败的 API 调用： “列出 /api/ 请求的网络错误，并解释为什么这个 POST 返回 500。”
• 边写代码边做无障碍检查： “对这个页面运行无障碍审计，并修复严重问题。”
• 性能与 SEO 评估： “运行性能审计，告诉我是什么拖累了 Core Web Vitals。”或在 Next.js 应用上使用 nextjsSeoAudit 提示词。
• 登录后页面的视觉验证： “给当前标签页截个图，看看我改完 CSS 后布局有没有乱。”

BrowserTools MCP Server 与替代方案对比

• Playwright MCP、Puppeteer MCP Server 和 Chrome DevTools MCP： 它们驱动的是一个全新的自动化浏览器，适合编写测试和脚本化自动化。BrowserTools 观察的是你正在使用的浏览器，并额外提供 Lighthouse 审计，但不会替你点击或填写表单。
• Browser MCP（browsermcp.io）： 名字相近，但是另一个项目。它同样由 MCP 服务器加 Chrome 扩展组成，并使用你现有的浏览器配置文件，但它面向的是浏览器自动化（改编自 Playwright MCP），而 BrowserTools 专注于调试数据和审计。如果你搜索 “browser mcp” 是想让 AI 助手操作网页，Browser MCP 或 Playwright MCP 更合适。

BrowserTools MCP Server 常见问题排查

• 采集不到任何数据： 运行 npx @agentdeskai/browser-tools-mcp --doctor。它会报告 Node 版本、连接器是否已启动、扩展是否已连接，以及截图目录是否可写。
• 安装时报 engines 错误： 2.0 在 engines 中声明了 Node 22.19+，因此旧版 Node 会在安装时失败。请升级 Node，并确保编辑器继承该版本。
• 缺少页面加载时的请求： 网络采集从打开 DevTools 时开始。重新加载页面即可采集完整的加载过程。
• 出现 “started debugging this browser” 提示条： 控制台采集默认使用 DevTools 协议。在面板中将采集模式切换为 Wrap page console 即可。
• 从 1.x 升级： 删除旧扩展，重新加载新的 chrome-extension 目录，并删除单独启动 browser-tools-server 的步骤。详见仓库中的 MIGRATION.md。