Chrome DevTools MCP：让 AI agent 真正接管浏览器调试

TL;DR

chrome-devtools-mcp 是 Google 官方出品的 MCP server，通过 CDP 把 Chrome DevTools 的核心能力——截图、Console 监控、网络请求、性能 trace、Lighthouse 审计——暴露给 AI agent。

配置只需两步：用 --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug 启动 Chrome，再在 VS Code 或 OpenCode 的 MCP 配置里加一个 npx chrome-devtools-mcp 条目。

它的定位是 " 调试感知 " 而非 " 自动化操控 “，让 agent 真正能看到浏览器的运行时状态。

一、当 AI agent 需要一双眼睛

浏览器是现代 web 开发的核心场景，但长期以来，AI coding agent 对它几乎是 " 盲的 “。

你可以让 agent 写代码、跑测试、读文档，但有一件事它做不到：打开浏览器，看看页面到底渲染成什么样，Console 里报了什么错，Network 请求是否符合预期。这不是智力问题，是感知问题——agent 没有手，也没有眼睛。

MCP（Model Context Protocol） 提供了标准化的工具调用协议，让 AI 能够以统一方式接入外部能力。而 chrome-devtools-mcp 就是在这个协议之上，把 Chrome DevTools 的核心能力——性能分析、DOM 操作、截图、Console 监控、网络请求抓取——全部暴露给 AI agent。

它由 Google 官方团队维护，上线半年获得近 3 万 star，这个数字说明了一件事：这个需求是真实的，而且足够普遍。

二、chrome-devtools-mcp 是什么

Chrome DevTools 本身是开发者最熟悉的调试工具——性能面板、元素检查、网络监控、Console 输出，每天都在用。但这些能力一直被封锁在人工操作的界面里，无法被程序化调用。

chrome-devtools-mcp 做的事情很直接：通过 Chrome DevTools Protocol（CDP），把这些能力以 MCP tool 的形式暴露出来，让任何支持 MCP 的 AI agent 都能直接调用。

它能做什么

核心能力覆盖六个维度：

• 截图与视觉感知：对当前页面或指定元素截图（take_screenshot），获取页面可访问性树快照（take_snapshot），让 AI 真正 " 看到 " 页面
• DOM 操作与交互：读取页面结构、查询元素、执行 JavaScript（evaluate_script），还能点击（click）、填写表单（fill）、拖拽（drag）、按键（press_key）
• Console 监控：获取 console.log / error / warn 输出（list_console_messages）
• 网络请求抓取：列出和分析页面的所有网络请求（list_network_requests / get_network_request）
• 性能分析：录制性能 trace（performance_start_trace），分析 Core Web Vitals（LCP、INP、CLS）等指标
• 审计报告：调用 Lighthouse 生成可访问性、SEO、最佳实践报告（lighthouse_audit，注意不含性能维度）

与 Puppeteer / Playwright MCP 的区别

这是一个常见的困惑。三者都能控制浏览器，但定位不同：

chrome-devtools-mcp 的核心优势在调试和感知——性能 trace、Console 监控、网络请求分析、Lighthouse 审计，这些是 Puppeteer / Playwright MCP 不具备的。同时它也提供了基础的页面交互能力（点击、填写、导航），足以覆盖大多数开发调试场景。

三、安装与配置

chrome-devtools-mcp 通过 npm 分发，核心依赖只有 Node.js 18+。

第一步：启动 Chrome 调试模式

MCP server 通过 CDP 连接 Chrome，需要先以调试端口启动浏览器：

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/chrome-debug

# Linux
google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug

# Windows
chrome.exe --remote-debugging-port=9222 --user-data-dir=%TEMP%\chrome-debug

--user-data-dir 指定一个独立的数据目录，这是启用远程调试的必要参数。用 /tmp/chrome-debug 这样的临时目录，既不会影响日常 Chrome 数据，也不需要先退出已有的 Chrome 实例。

启动后访问 http://localhost:9222/json，能看到页面列表说明 CDP 连接就绪。

第二步：接入 AI 客户端

VS Code（GitHub Copilot）

打开命令面板 Cmd/Ctrl+Shift+P → Preferences: Open User Settings (JSON)，添加：

{
  "mcp": {
    "servers": {
      "chrome-devtools": {
        "command": "npx",
        "args": ["-y", "chrome-devtools-mcp"],
        "env": {
          "CHROME_DEBUGGING_PORT": "9222"
        }
      }
    }
  }
}

也可以用工作区级别的 .vscode/mcp.json，但写在 user settings 里可以全局生效。

OpenCode

在 ~/.config/opencode/opencode.json 中添加：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp"],
      "env": {
        "CHROME_DEBUGGING_PORT": "9222"
      }
    }
  }
}

常见坑

• 必须指定 --user-data-dir：远程调试要求使用非默认数据目录，否则会报错。指定后可以与日常 Chrome 并行运行，互不影响
• WSL 用户：Chrome 运行在 Windows 侧，端口映射通常没问题，偶尔需要改用宿主机 IP 替代 localhost
• 端口冲突：9222 被占用时换一个端口，env 里同步修改即可

四、三个真实场景

配置完成后，在 VS Code 或 OpenCode 的 agent 模式中，直接用自然语言描述需求即可。

场景一：性能分析

打开一个页面后，对 agent 说：

" 帮我分析当前页面的性能，找出主要瓶颈 "

agent 会调用 performance_start_trace 录制性能 trace，自动重新加载页面，收集 LCP、INP、CLS 等 Core Web Vitals 指标，然后通过 performance_analyze_insight 逐项分析瓶颈——哪些资源阻塞了首屏渲染、布局偏移来自哪个元素、长任务发生在什么阶段。

注意，lighthouse_audit 是另一个 tool，它生成的是可访问性、SEO 和最佳实践报告，明确不包含性能维度。性能分析用 trace，审计报告用 Lighthouse，两者互补。

过去这个流程是：手动打开 DevTools → 录制 Performance → 读火焰图 → 自己分析。现在 agent 把后三步全包了。

场景二：错误排查

线上页面白屏，不确定是哪里报错：

" 获取当前页面的 Console 错误，帮我定位问题 "

agent 调用 list_console_messages tool（可以按 error、warn 等类型过滤），把所有错误信息取回来，结合页面 DOM 结构给出判断。如果需要，还可以通过 evaluate_script 直接执行 JavaScript 验证假设：

" 在当前页面执行 document.querySelectorAll('.btn').length，看看按钮渲染了多少个 "

场景三：截图与视觉回归

UI 改动后想确认效果：

" 截一张当前页面的截图，对比一下导航栏是否对齐 "

agent 调用 take_screenshot tool（支持全页截图、指定元素截图、多种格式），返回图片，直接在对话中 " 看到 " 页面现状。配合代码修改，可以做简单的视觉回归验证——改完代码，截图，让 agent 判断是否符合预期。

一个关键认知

这三个场景的共同点：agent 在 " 观察 " 浏览器的运行时状态，然后给出判断和建议。这正是 chrome-devtools-mcp 区别于 Playwright / Puppeteer MCP 的核心价值——它不只是操控浏览器，更重要的是让 AI 具备了 DevTools 级别的感知和诊断能力。

五、边界与安全

它能做什么，不能做什么

chrome-devtools-mcp 通过 CDP 暴露了相当全面的能力，覆盖调试感知和基础交互两个维度：

• 能做：读取 DOM、执行 JS、抓取网络请求、截图、跑 Lighthouse 审计、录制性能 trace、点击元素、填写表单、键盘输入、页面导航、设备模拟
• 不能做：跨浏览器支持（只支持 Chrome/Chromium）、复杂的多步自动化流程编排、文件下载管理

与 Playwright MCP 相比，chrome-devtools-mcp 的交互能力已经足够覆盖日常调试场景，但在复杂的 E2E 自动化测试方面，Playwright 的抽象层和跨浏览器支持仍然更成熟。

安全边界：一个值得认真对待的问题

--remote-debugging-port 打开后，任何能访问该端口的进程都可以完全控制这个 Chrome 实例——读取 Cookie、截取页面内容、执行任意 JavaScript。

几个必须注意的点：

• 不要在登录了银行、邮件等敏感账号的 Chrome 上开启调试端口，建议用单独的 Chrome Profile 或 Chromium 实例专门用于开发调试
• 调试端口不要暴露到公网，默认绑定 localhost 是安全的，加了 --remote-debugging-address=0.0.0.0 就危险了
• AI 执行 JS 的风险：agent 可以通过 evaluate_script tool 在页面上下文执行任意 JavaScript，理论上可以读取页面上的所有数据。在生产环境或包含敏感信息的页面上要谨慎

六、现在能用吗？

chrome-devtools-mcp 目前处于可用但仍在演化的阶段。

核心功能——截图、Console 日志、DOM 查询、Lighthouse——是稳定可用的，日常开发调试场景完全够用。但它不是一个 " 生产级别的成熟工具 “，API 设计还在调整，偶尔会有 breaking change。

值得期待的方向

当前的主要局限是只支持本地 Chrome 实例。后续可能的演化方向：

• 支持远程 Chrome 实例，让 CI 环境也能接入
• 多 tab 并发监控，配合多 agent 协作
• 更深度的性能分析能力，如内存泄漏自动检测

一个更大的命题

chrome-devtools-mcp 解决的其实是一个基础设施问题：让 AI agent 能够感知运行时状态，而不只是静态代码。

代码可以通过 AST 分析，文档可以通过 RAG 检索，但页面的实际渲染状态、运行时的网络行为、JavaScript 执行后的 DOM 变化——这些只存在于运行时，过去对 AI 是不透明的。

chrome-devtools-mcp 打开了一扇窗。这扇窗通向哪里，取决于 AI agent 能力的整体演化速度。