chrome-devtools-mcp：把 Chrome DevTools 装进 AI 编码代理

ChromeDevTools/chrome-devtools-mcp 是 Chrome DevTools 官方团队在 2026 年主推的项目（截至 2026-07-02 达 44,941 Star，单日新增 92）。它的定位非常精确：把 DevTools 完整能力通过 Model Context Protocol（MCP）暴露给 Claude、Cursor、Copilot、Antigravity、Codex、Gemini CLI 这类编码代理，让代理拥有真正的"可观察、可操作"浏览器——不再只是给出截图和 console log，而是能驱动真实 Chrome 实例去做自动化、调试、性能分析。

往深看，它的核心价值不在于"又一个浏览器自动化工具"（这一直是 Puppeteer / Playwright 的领地），而在于DevTools 能力的语义化封装：

• 拿 LCP / CLS / FCP 数字而不是 50k 行 trace JSON
• 拿"DOM 节点 + 无障碍树 + 关键属性"快照而不是整页 HTML
• **拿"网络请求 + 关键 headers + 状态码"**而不是原始 HAR
• **拿"heap 增长分类 + dominator 链"**而不是 .heapsnapshot 文件本身

这条"语义化 → 压缩 → 适合 LLM 上下文窗口"的设计哲学贯穿整个仓库，是它跟 Puppeteer 的本质差异。

学习目标

读完本文，你应该能够：

• 说清 chrome-devtools-mcp 与 Puppeteer / Playwright 的本质差异——不是"又一个浏览器自动化工具"，而是 DevTools 能力的语义化封装。
• 根据调试场景在"内置 Chrome 实例"与"连接现有 Chrome"两条启动路径之间做选择。
• 用 slim 模式与类别开关（--category*）控制 51 个工具对上下文窗口的占用。
• 跟着任务流案例，用 performance_* 工具完成一次 LCP 劣化的端到端诊断。
• 判断哪些场景适合采用、哪些场景（高敏数据、纯后端）应该避开。

目录

• 系统地图：51+ 工具按能力切片
• 双模式启动：内置 Chrome 还是连接现有 Chrome
  • 路径 A：内置 Chrome 实例（默认）
  • 路径 B：连接现有 Chrome（sandboxed / 共享登录态）
• 任务流案例：性能问题的端到端诊断
• 设计原则（来自 docs/design-principles.md）
• 隐私与统计：使用数据默认开启
• 版本节奏：从 2026-05 到 2026-06 的密集发布
• 适用边界与采用顺序
  • 适合采用
  • 不适合采用
  • 推荐的接入顺序
• 仓库元信息

系统地图：51+ 工具按能力切片

仓库当前默认暴露 51 个工具（含 1 个 slim 套餐），按能力分组：

slim 模式只保留三个：navigate_page + evaluate_script + take_screenshot，适合"我只要打开页面看一眼"的轻量场景，避免一次性把 51 个工具描述塞进上下文窗口。

类别间有清晰的开关：

npx -y chrome-devtools-mcp@latest \
  --categoryEmulation=false \
  --categoryPerformance=true \
  --categoryNetwork=true \
  --categoryExtensions=true \
  --memoryDebugging

--categoryEmulation、--categoryPerformance、--categoryNetwork 默认为 true；--categoryExtensions 和 --memoryDebugging 默认关闭——这两个类别工具描述加起来相当长，工程上做了"按需加载"的折中。

双模式启动：内置 Chrome 还是连接现有 Chrome

跟 Puppeteer 不同，chrome-devtools-mcp 把"启动浏览器"这件事做成了两条互斥路径：

路径 A：内置 Chrome 实例（默认）

第一次调用需要浏览器的工具时，服务器会自动启动一个 Chrome stable 通道实例，使用专用 user-data-dir：

• Linux / macOS: $HOME/.cache/chrome-devtools-mcp/chrome-profile-$CHANNEL
• Windows: %HOMEPATH%/.cache/chrome-devtools-mcp/chrome-profile-$CHANNEL

默认 user-data-dir 不会在每次运行后清理，跨实例共享。如果想完全隔离：

npx -y chrome-devtools-mcp@latest --isolated

--isolated 会创建一个临时 user-data-dir，浏览器关闭后自动清理。

路径 B：连接现有 Chrome（sandboxed / 共享登录态）

某些场景默认启动不适用：

• 想在手工测试和代理驱动测试之间保留同一个应用状态（同一窗口、同一登录态、同一表单数据）
• 代理需要登录，但 WebDriver 控制下的 Chrome 被某些账号风控拒绝
• LLM 跑在沙箱里，但想让浏览器跑在沙箱外（让用户能看到真实渲染）

这种情况下要先启动带远程调试端口的 Chrome，再用 --browser-url 或 --ws-endpoint 连过去：

# 先开 Chrome（macOS）
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/chrome-profile-stable

# 再启动 MCP server
npx -y chrome-devtools-mcp@latest --browser-url=http://127.0.0.1:9222

Chrome 144+ 还提供了 --autoConnect 模式：通过 chrome://inspect/#remote-debugging 启用远程调试，配置 --autoConnect 后 MCP server 会自动定位当前用户配置的 default profile 并发起连接，弹出对话框让用户授权。这条路径省去了手动开 Chrome 的步骤，但需要用户在场。

注意 Chrome 要求"启用远程调试端口必须使用非默认 user-data-dir"——这是 Chrome 内置的安全约束，不是 MCP server 加的。共享常规浏览 profile 给调试会话是危险的（任何本机进程都能连 9222 操控浏览器），所以 MCP server 强制 --user-data-dir=/tmp/... 隔离。

任务流案例：性能问题的端到端诊断

下面是 chrome-devtools-mcp 配合 Claude Code 的典型工作流——一次 LCP（最大内容绘制时间）突然劣化后的诊断全过程：

1. 触发。用户在 Claude Code 输入：

我们的产品页 LCP 最近从 1.8s 退化到 4.2s，看看是不是新加的 hero 图影响的。

2. 代理发现 + 启动。Claude Code 通过 MCP 拿到 chrome-devtools-mcp 的 51 个工具，第一次调用 navigate_page 时 MCP server 自动启动 Chrome stable 实例。

3. trace 采集。代理依次调用 performance_start_trace → navigate_page 打开产品页 → 等待关键渲染 → performance_stop_trace。trace 文件被保存为本地路径（不是原始 JSON 内联返回——这是 chrome-devtools-mcp 的关键设计选择，见下文）。

4. 关键洞察抽取。代理调用 performance_analyze_insight，MCP server 调用 DevTools frontend 的 trace 分析能力，返回结构化结论：

{
  "insights": [
    {"name": "LCP", "value": "4.12s", "element": "img.hero-banner"},
    {"name": "Render-blocking resources", "value": "1 stylesheet, 142ms"},
    {"name": "Largest network payload", "value": "img.hero-banner (2.4MB, no srcset)"}
  ]
}

5. 真实用户数据交叉验证（CrUX 集成）。默认配置下，性能工具会把 trace URL 发到 Google CrUX（Chrome User Experience Report）API 取真实用户数据，让"实验室测量"与"真实用户体验"对齐。如果不想上传 URL，加 --no-performance-crux：

npx -y chrome-devtools-mcp@latest --no-performance-crux

6. 生成修复建议。代理根据结构化洞察生成建议：“hero 图 2.4MB 没 srcset，LCP 4.12s 主要在图片加载；加响应式 srcset + AVIF，预计 LCP 回到 1.8s 附近。”

整条链路里代理从来没有看到 trace 的 50k 行 JSON——MCP server 把它解析成 LCP / 阻塞资源 / 最大 payload 等概念。这是 chrome-devtools-mcp 跟 Playwright + 人工看 trace 的根本差异。

设计原则（来自 docs/design-principles.md）

仓库的官方设计原则共 7 条，每条都对架构选择有直接影响：

第 2 条（Token-Optimized）和第 7 条（Reference over Value）合起来构成了"截图缩放"的设计：截图默认是 PNG，但 JPEG/WebP 体积小 3-5 倍；--screenshotMaxWidth / --screenshotMaxHeight 在源头做降采样。这两个选项的注释直白写了"Reduces context size in AI conversations"——是为 LLM 上下文窗口做的工程取舍。

隐私与统计：使用数据默认开启

README 第一段 Disclaimer 把边界写得很清楚：

chrome-devtools-mcp exposes content of the browser instance to the MCP clients allowing them to inspect, debug, and modify any data in the browser or DevTools. Avoid sharing sensitive or personal information that you don’t want to share with MCP clients.

也就是说 MCP server 看到的所有浏览器内容都暴露给代理。这条不是 bug，是设计——但使用前需要明确边界。

另一个默认开启的边界是使用统计：

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest", "--no-usage-statistics"]
    }
  }
}

默认收集"工具调用成功率、延迟、环境信息"，按 Google Privacy Policy 处理。--no-usage-statistics 关闭，或设 CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS / CI 环境变量也会自动关闭。

只支持 Google Chrome 和 Chrome for Testing——其他 Chromium 内核浏览器（Edge / Brave / Arc）可能工作但不保证。

版本节奏：从 2026-05 到 2026-06 的密集发布

CHANGELOG 显示这是一个节奏非常快的项目，2026-05-27 到 2026-06-23 之间连发了 1.1.1 / 1.2.0 / 1.3.0 / 1.4.0：

• v1.2.0（2026-06-08）：启用内存调试工具（--memoryDebugging）、allowed/blockedUrlPattern、close_heapsnapshot、实验性 TOON 结构化输出
• v1.3.0（2026-06-18）：新增 get_heapsnapshot_dominators / retaining paths / edges，截图 CLI 加尺寸限制，list_pages 加 title
• v1.4.0（2026-06-23）：发布 skills 文件夹，让 Claude Code 既能拿 MCP server 也能拿配套技能（之前只能装 MCP）

一个明显趋势是**“工具集从开发者向代理迁移”**：v1.2 的内存调试工具、v1.3 的 dominator / retaining paths 都是给代理做"AI 内存分析"用的——传统开发者用 Chrome DevTools 自己看 .heapsnapshot 文本，不会主动要 dominator 链；代理需要。

适用边界与采用顺序

chrome-devtools-mcp 是"前端调试 AI 化"的事实标准入口之一，但用之前需要分清边界：

适合采用

• 前端 bug 排查需要"看真实浏览器行为"而不是看代码
• 性能优化（LCP / CLS / INP）需要持续测量与回归保护
• 自动化 e2e 测试想要 LLM 驱动而不是手写脚本
• 调试"只在生产环境、特定用户、特定设备下出现"的诡异问题
• 内存泄漏调查（–memoryDebugging 启用后）

不适合采用

• 后端 / Node 服务 / API 调试——用对应语言的 debugger，不要经过浏览器
• 单纯截图任务（Playwright / Puppeteer 已够，chrome-devtools-mcp 是更重的选项）
• 不信任代理看到浏览器内容的高敏场景（任何登录态、任何表单数据都会暴露给代理）
• 没有 Chrome stable 通道的环境

推荐的接入顺序

1. 先用 slim 模式。npx -y chrome-devtools-mcp@latest --slim --headless 只暴露 3 个工具，验证 MCP 配置和权限链路。
2. 再开 input automation + navigation。这是 90% LLM 自动化任务的最小集合。
3. 按需开启 performance / network / memory。每个类别的工具描述都会进上下文窗口，按需打开比"全开"更省 token。
4. 生产环境慎用 autoConnect。--autoConnect 需要用户在现场授权（弹窗），适合本地开发不适合 CI/CD。

仓库元信息

如果只是想"让代理能截图并执行 JS"，slim 模式 + Claude Code 的 plugin 安装是 5 分钟可用的最小路径。如果要做"AI 驱动的端到端浏览器调试"，chrome-devtools-mcp 是当前 MCP 生态里唯一一个把 DevTools 完整语义能力封装成代理工具的项目——这一点它暂时没有直接对手。

自测题

1. chrome-devtools-mcp 与 Puppeteer / Playwright 的本质区别在哪？
2. slim 模式默认保留哪三个工具？它解决了什么工程问题？
3. 路径 A（内置 Chrome）与路径 B（连接现有 Chrome）分别在什么场景下更合适？
4. 任务流案例里 performance_analyze_insight 返回的是 trace JSON 吗？它实际给代理的是什么？
5. CrUX 集成默认是开启还是关闭？不想把 URL 发给 Google 该加什么参数？
6. 使用统计默认开启，有哪几种关闭方式？

参考答案

1. 不是"又一个浏览器自动化工具"，而是把 DevTools 能力做语义化封装：给 LCP/CLS/FCP 数字、给 DOM 快照 + 无障碍树、给网络请求摘要，而不是 50k 行 trace JSON、整页 HTML 或原始 HAR。这让 LLM 上下文窗口用得起来。
2. 只留 navigate_page + evaluate_script + take_screenshot。51 个工具的描述全塞进上下文会很贵，slim 适合"打开页面看一眼"的轻量场景，先验证配置和权限链路。
3. 路径 A 让服务器自动起一个 Chrome stable 实例，最简单；路径 B 是连一个你手动启动、带 --remote-debugging-port 的 Chrome，适合要保留登录态/应用状态、要绕过 WebDriver 风控、或让浏览器跑在沙箱外的场景。--autoConnect 介于两者之间，但需要用户在场授权。
4. 不是 JSON。trace 文件被保存为本地路径（重型资产返回路径而非原始字节），performance_analyze_insight 再调用 DevTools 前端的 trace 分析能力，返回"LCP 4.12s / 阻塞资源 / 最大 payload"这类结构化结论。
5. 默认开启（会把 trace URL 发到 Google CrUX API 取真实用户数据）。加 --no-performance-crux 即可关闭上传。
6. 三种：--no-usage-statistics 命令行参数、环境变量 CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS、或设 CI 环境变量（CI 下自动关闭）。

练习

1. 用 npx -y chrome-devtools-mcp@latest --slim --headless 起一个 MCP server，在 Claude Code / Cursor 里验证它能列出三个工具并完成一次截图。
2. 打开任意一个网页，用 evaluate_script 在页面上下文里取出某个 DOM 节点的 textContent 或某个全局变量的值。
3. 复现任务流案例：对某个慢页面跑 performance_start_trace → 导航 → performance_stop_trace → performance_analyze_insight，对比"有 srcset"和"无 srcset"两种 hero 图下的 LCP。
4. 手动启动带 --remote-debugging-port=9222 的 Chrome（先登录一个站点），再用 --browser-url=http://127.0.0.1:9222 连接过去，确认代理能操作你已经登录的页面。
5. 加 --memoryDebugging 启动，对一个已知会泄漏内存的页面依次 take_heapsnapshot → 操作 → compare_heapsnapshots_summary，看 dominator 链指向哪类对象。

进阶路径

• 读 docs/design-principles.md 七条原则，重点看 Token-Optimized 与 Reference over Value 如何共同决定"截图降采样、trace 返回路径"这些取舍。
• 翻 src/tools/ 下的工具注册代码，理解每个工具如何把 DevTools 协议调用收束成一个语义化返回。
• 写一个 Third-party 类别的自定义 developer tool（list_3p_developer_tools / execute_3p_developer_tool），把你们内部平台的能力暴露给代理。
• 把 CrUX API 与你们自己的 RUM 数据对齐，让代理的"修复建议"同时参考真实用户指标和实验室测量。

常见问题 FAQ

Q：只能用在 Google Chrome 上吗？Edge / Brave / Arc 行不行？ 官方只支持 Google Chrome 和 Chrome for Testing。其它 Chromium 内核浏览器"可能工作但不保证"——因为它们未必实现完整的 DevTools 远程调试协议细节。生产环境别赌这个。

Q：代理会看到我的登录态和表单数据吗？ 会。MCP server 看到的所有浏览器内容都暴露给代理，这是设计使然（README 第一段 Disclaimer 写明了）。高敏场景要么用隔离的 --isolated profile，要么干脆不接这类页面。

Q：--autoConnect 为什么不适合 CI？ 因为它需要用户在 chrome://inspect 弹窗里手动授权，依赖"人在现场"。CI 里没有人点确认，链路会卡住。CI 用路径 B 的 --browser-url 显式连接更稳。

Q：trace / 截图这些文件存哪了，怎么清理？ 默认 user-data-dir 跨实例共享、不会自动清理（路径在 $HOME/.cache/chrome-devtools-mcp/）。要彻底隔离就在启动时加 --isolated，浏览器关闭后临时目录自动删除。

Q：51 个工具把上下文撑爆了怎么办？ 用类别开关关掉不用的：--categoryExtensions=false、--memoryDebugging（默认就关）等。--categoryEmulation / --categoryPerformance / --categoryNetwork 默认开，按需保留。

Q：工具报错了有没有自带排错指引？ 有。设计原则里的 Self-Healing Errors 要求错误信息自带上下文和可能的修复建议，代理能基于错误自己重试或换路径，不需要你从零读堆栈。