chrome-devtools-mcp 实战：让编码 Agent 驱动真实 Chrome 完成自动化、调试与性能分析

chrome-devtools-mcp 是官方提供的 Chrome DevTools MCP 服务器，它把你的编码 Agent（Antigravity、Claude、Cursor、Copilot 等）与一个真实运行的 Chrome 浏览器连接起来，使 AI 助手可以直接调用 DevTools 的全部能力：录制性能 trace、分析网络请求、抓取控制台日志、驱动页面交互。读完本篇，你将掌握其标准安装配置、--slim 精简模式、全部服务器参数（含 WebSocket 连接方式）、使用统计与隐私开关，以及无需 MCP 的 CLI 用法，并能从源码层面理解浏览器是如何被按需启动和复用的。

一、它是什么：三大核心能力

根据 README 的定义，chrome-devtools-mcp 作为一个 MCP（Model-Context-Protocol）服务器运行，为 AI 编码助手提供三大能力：

• 性能洞察（Performance insights）：基于 Chrome DevTools（devtools-frontend）录制性能 trace，并从中提取可操作的优化建议。
• 高级浏览器调试（Advanced browser debugging）：分析网络请求、截图、读取浏览器控制台消息（带 source-map 还原后的堆栈）。
• 可靠自动化（Reliable automation）：使用 puppeteer 在 Chrome 中执行操作，并自动等待操作结果，避免"点了但页面还没就绪"这类竞态问题。

从 package.json 可以看到实现事实：项目依赖 puppeteer 25.9.0 和 lighthouse 13.4.1，Node 引擎要求为 ^20.19.0 || ^22.12.0 || >=23（即 Node LTS 或更新版本），当前版本为 1.8.0。仓库中 third_party/devtools-frontend 以子模块形式引入，印证了"trace 录制与格式化直接复用 DevTools 前端代码"的说法。

二、运行要求与快速开始

环境要求

README 明确列出三项要求：

• Node.js：LTS 版本（仓库 engines 字段进一步限定为 ^20.19.0 || ^22.12.0 || >=23）；
• Chrome：当前稳定版或更新版本；
• npm：用于通过 npx 拉取包。

标准安装：在 MCP 客户端中加一段配置

在你的 MCP 客户端配置中加入：

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

使用 chrome-devtools-mcp@latest 可以让 MCP 客户端始终使用最新版服务器。

各编辑器/Agent 的具体接入方式（Antigravity、Claude Code、Cursor、VS Code、Gemini CLI、Cline、Windsurf 等十余种客户端）见 MCP Client configuration 指南。几个典型例子：

• Claude Code：claude mcp add chrome-devtools --scope user npx chrome-devtools-mcp@latest；也可以以插件形式安装（MCP + Skills 一起加载）。
• Gemini CLI：gemini mcp add chrome-devtools npx chrome-devtools-mcp@latest。
• VS Code / Copilot：推荐以 Agent Plugin 方式安装（Command Palette 中执行 Chat: Install Plugin From Source，输入仓库名），可同时获得 MCP 服务器与全部 skills。
• Codex：codex mcp add chrome-devtools -- npx chrome-devtools-mcp@latest，Windows 11 上还需在 ~/.codex/config.toml 中补充 env 与 startup_timeout_ms 配置。

精简模式：--slim

如果只需要完成基础的浏览器任务（导航、执行脚本、截图），使用 slim 模式：

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest", "--slim", "--headless"]
    }
  }
}

slim 模式只暴露 3 个工具，完整清单见 Slim tool reference：

工具	分类	参数	说明
navigate	Navigation	url（string，必填）	加载 URL
evaluate	Debugging	script（string，必填）	在页面执行 JS
screenshot	Debugging	无	截图

源码印证：createTools 中，args.slim 为真时直接返回 slim 工具集，否则聚合 console、emulation、input、lighthouse、network、performance、pwa、screencast、screenshot、script、snapshot 等十几个模块的全部工具，并按工具名排序后注册。slim 工具的实现见 slim/tools.ts：navigate 内部调用 puppeteer 的 page.goto 并设置 30 秒超时、自动接受 beforeunload 对话框；screenshot 以 optimizeForSpeed 模式截图后落盘为临时文件返回路径。

第一个 Prompt：验证链路

在 MCP 客户端中输入：

Check the performance of https://developers.chrome.com

客户端应打开浏览器并录制一次性能 trace。需要注意 README 中的关键说明：

MCP 服务器不会在客户端只是"连接"时自动启动浏览器；只有当客户端调用到需要浏览器的工具时，服务器才会自动拉起浏览器实例。

这一点可以从源码得到印证：src/index.ts 中 McpServer 的工具注册只登记了工具定义，真正的浏览器启动发生在工具调用时——ToolHandler 通过 () => this.#getContext() 惰性获取上下文，#getContext()（src/index.ts#L204-L281）内部根据参数走 ensureBrowserLaunched（自行启动）或 ensureBrowserConnected（连接已有实例）两条路径之一，并且缓存同一个 McpContext，只有浏览器实例变化时才重建上下文。

三、服务器参数全解

README 将完整参数清单指向 Configuration Guide。该文档的参数区是自动生成的（源码中用 BEGIN/END AUTO GENERATED OPTIONS 注释标记），与 src/config/mcp-options.ts 保持同步。参数统一通过 JSON 配置的 args 属性传递，例如：

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "chrome-devtools-mcp@latest",
        "--channel=canary",
        "--headless=true",
        "--isolated=true"
      ]
    }
  }
}

以下按用途分组完整继承配置指南中的参数说明：

浏览器连接类

参数	类型/默认值	说明
--browserUrl / -u	string，默认 false	连接已运行且可调试的 Chrome 实例（如 http://127.0.0.1:9222）
--wsEndpoint / -w	string，默认 false	直接连接 WebSocket 端点（如 ws://127.0.0.1:9222/devtools/browser/<id>），--browserUrl 的替代方案
--wsHeaders	string，默认 false	WebSocket 连接的自定义请求头，JSON 格式（如 {"Authorization":"Bearer token"}），仅与 --wsEndpoint 配合
--autoConnect	boolean，默认 false	自动连接用户数据目录中（由 --channel 识别，默认 stable）本地运行的 Chrome 144+ 实例；需先在 chrome://inspect/#remote-debugging 开启远程调试

带自定义请求头的 WebSocket 连接示例（配置指南原文）：

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "chrome-devtools-mcp@latest",
        "--wsEndpoint=ws://127.0.0.1:9222/devtools/browser/<id>",
        "--wsHeaders={\"Authorization\":\"Bearer YOUR_TOKEN\"}"
      ]
    }
  }
}

获取端点的方法：访问 http://127.0.0.1:9222/json/version，读取 webSocketDebuggerUrl 字段。也可运行 npx chrome-devtools-mcp@latest --help 查看全部选项。

浏览器启动与运行环境类

参数	类型/默认值	说明
--headless	boolean，默认 false	无 UI 模式运行
--executablePath / -e	string	自定义 Chrome 可执行文件路径
--isolated	boolean，默认 false	使用临时 user-data-dir，浏览器关闭后自动清理
--userDataDir	string	Chrome 用户数据目录。默认 $HOME/.cache/chrome-devtools-mcp/chrome-profile（非 stable 渠道会附加渠道后缀）
--channel	string，可选 canary/dev/beta/stable	指定 Chrome 渠道，默认 stable
--viewport	string	初始视口，如 1280x720；headless 模式下最大 3840x2160
--proxyServer	string	传递给 Chrome --proxy-server 的代理配置
--acceptInsecureCerts	boolean，默认 false	忽略自签名/过期证书错误，谨慎使用
--chromeArg	array	附加的 Chrome 启动参数，仅在由服务器启动 Chrome 时生效
--ignoreDefaultChromeArg	array	显式禁用默认 Chrome 参数
--logFile	string	调试日志文件路径；配合 DEBUG=* 环境变量获得详细日志

源码印证：#getContext() 中的分支逻辑（src/index.ts#L222-L253）——只要设置了 browserUrl、wsEndpoint 或 autoConnect 三者之一，就走 ensureBrowserConnected（wsHeaders 在此路径生效，channel 仅在 autoConnect 时传入）；否则走 ensureBrowserLaunched，把 headless、executablePath、channel、isolated、userDataDir、viewport、chromeArgs、acceptInsecureCerts 等逐项传入。这也解释了"连接模式下浏览器不会自动启动"的原因：该路径只做连接，不做启动。

工具类别开关

参数	类型/默认值	说明
--slim	boolean，默认 false	只暴露导航、脚本执行、截图 3 个工具
--categoryEmulation	boolean，默认 true	设为 false 排除模拟类工具
--categoryPerformance	boolean，默认 true	设为 false 排除性能类工具
--categoryNetwork	boolean，默认 true	设为 false 排除网络类工具
--categoryExtensions	boolean，默认 false	包含扩展类工具；当前仅支持 pipe 连接，autoConnect/browserUrl/wsEndpoint 在 149 版本发布前不兼容此特性
--categoryPwa	boolean，默认 false	包含 PWA 自动化（安装、启动、卸载、OS 状态）；仅支持 pipe 连接
--categoryExperimentalThirdParty	boolean，默认 false	启用被检页面自身暴露的第三方开发者工具

实验性（Experimental）特性

参数	类型/默认值	说明
--experimentalDevtools	boolean，默认 false	启用对 DevTools target 的自动化
--experimentalVision	boolean，默认 false	启用 click_at(x,y) 等基于坐标的工具，通常需要能看图产出坐标的 computer-use 模型
--memoryDebugging（别名 --experimentalMemory）	boolean，默认 false	启用内存调试工具
--experimentalStructuredContent	boolean，默认 false	输出结构化格式内容
--experimentalIncludeAllPages	boolean，默认 false	将 webview、后台页等所有页面类型纳入 pages
--experimentalScreencast	boolean，默认 false	暴露实验性录屏工具（需要 PATH 中可用的 ffmpeg）
--experimentalFfmpegPath	string	录屏用 ffmpeg 可执行文件路径
--experimentalScreencastFps	number	录屏帧率；页面出帧快于 ffmpeg 编码时，降低帧率可减轻内存压力

安全、网络与截图类

参数	类型/默认值	说明
--pageIdRouting	boolean，默认 true	要求页面级工具携带 pageId 并按 pageId 路由（多 Agent 并发会话场景）；--no-page-id-routing 关闭
--blockedUrlPattern	array	按 WHATWG URLPattern 屏蔽 URL，连接时静默脱离被屏蔽的 target，并拦截运行时请求（含导航与子资源）
--allowedUrlPattern	array	白名单模式，需 Chrome 149+
--redactNetworkHeaders	boolean，默认 false	返回网络头前脱敏敏感头
--javascriptEvaluation	boolean，默认 true	设为 false 禁用 JS 执行：禁用 evaluate_script 与 slim 的 evaluate，关闭 navigate_page 的 initScript，禁止导航到 javascript:/data:/vbscript: URL
--screenshotFormat	jpeg/png/webp	take_screenshot 的默认格式；JPEG/WebP 比 PNG 小约 3-5 倍
--screenshotQuality	number（0-100）	JPEG/WebP 压缩质量，PNG 忽略
--screenshotMaxWidth / --screenshotMaxHeight	number	超宽/超高时按等比缩小，减小 AI 对话的上下文体积；两者可叠加，取较小缩放系数
--performanceCrux	boolean，默认 true	设为 false 停止向 CrUX API 发送 trace URL
--usageStatistics	boolean，默认 true	设为 false 退出使用统计收集
--allowUnrestrictedPaths	boolean，默认 false	客户端未协商 roots 能力时解除"文件写入仅限 OS 临时目录"的默认限制；仅用于可信本地客户端
--filesystemRoot / --workspace	array，默认 OS 临时目录	文件系统工具可访问的目录，可多次指定

关于路径限制的补充：从 src/index.ts#L97-L121 可以看到，客户端未协商 MCP roots 能力且未配置 --filesystemRoot 时，服务器会打印警告并默认把文件写入限制到 OS 临时目录；#combinedRoots() 会合并 CLI 配置的 roots 与客户端上报的 roots，--allowUnrestrictedPaths 则直接清空配置侧 roots。

四、隐私与遥测：使用统计、CrUX 与更新检查

README 的 Disclaimers 与 Usage statistics 章节包含三条必须知道的合规信息：

1. 浏览器内容暴露风险：服务器会把浏览器实例的内容暴露给 MCP 客户端，客户端可以检查、调试、修改浏览器或 DevTools 中的任意数据。不要在其中放置你不愿共享的敏感或个人信息。
2. 官方支持范围：仅官方支持 Google Chrome 和 Chrome for Testing；其他 Chromium 内核浏览器"可能可用但不保证"。团队承诺修复并支持最新的 Extended Stable Chrome 版本。
3. CrUX 字段数据：性能工具可能把 trace URL 发送到 Google CrUX API 获取真实用户体验（RUM）数据，与实验室数据一起呈现。用 --no-performance-crux 关闭。

使用统计（Usage statistics）：默认开启，收集工具调用成功率、延迟与环境信息。退出方式：

"args": ["-y", "chrome-devtools-mcp@latest", "--no-usage-statistics"]

另外两条退出通道：设置 CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS 或 CI 环境变量时收集自动禁用。注意该统计独立于 Chrome 浏览器自身的 metrics——退出 Chrome 指标不会连带退出本工具，反之亦然。

更新检查（Update checks）：默认定期查询 npm registry，发现新版本时打印日志通知；设置 CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS 环境变量可关闭。

源码印证：启动时若 usageStatistics 为真，src/index.ts#L72-L82 会初始化 ClearcutLogger（含文件持久化 FilePersistence，支持自定义上报端点与强制刷盘间隔等参数）；客户端连接后，oninitialized 回调会记录客户端名称（src/index.ts#L97-L101）。而 README 中列出的三条免责声明，正是服务器启动时由 logDisclaimers 打印到 stderr 的：浏览器内容暴露警告始终打印；CrUX 与使用统计警告则分别受 slim 与对应开关控制（slim 模式下不打印）。

五、CLI 模式：不用 MCP 也能用

CLI 指南 说明包内附带一个实验性 CLI（chrome-devtools 命令，见 package.json 的 bin 字段，与 MCP 服务器二进制 chrome-devtools-mcp 并存）：

npm i chrome-devtools-mcp@latest -g
chrome-devtools status   # 检查安装

关键机制：

• 后台 daemon：CLI 是客户端，通过 Unix socket（Linux/Mac）或命名管道（Windows）与后台 chrome-devtools-mcp daemon 通信；
• 自动启动：首次调用工具（如 list_pages）时自动拉起 MCP 服务器与浏览器；
• 状态保持：后续命令复用同一后台实例，保留已打开页面、cookie 等状态；
• 手动控制：start/stop/status。start 的后续参数会透传给 MCP 服务器（如 --headless、--userDataDir）；Headless 默认开启，未提供 --userDataDir 时 Isolated 默认开启；
• 文件系统：CLI 默认允许不受限的文件访问，用 --workspace（可重复）限制文件工具目录；--allow-unrestricted-paths 单独仍可用，但不能与 --workspace 组合。

常用示例：

chrome-devtools start --workspace=/path/to/project --workspace=/path/to/output
chrome-devtools new_page "https://example.com"
chrome-devtools navigate_page 1 --url "https://web.dev"
chrome-devtools click 1 "element-uid-123"          # 按快照中的 UID 点击
chrome-devtools fill 1 "input-uid-456" "search query"
chrome-devtools evaluate_script "() => document.title" --pageId 1
chrome-devtools take_screenshot 1 --filePath screenshot.png
chrome-devtools lighthouse_audit 1 --mode snapshot
chrome-devtools list_pages --output-format=json     # 机器可读输出
chrome-devtools stop

调用规则：chrome-devtools <tool> [arguments] [flags]，必填参数用位置参数（页面级工具第一个位置参数为 <pageId>），可选参数用 flag。CLI 只支持 MCP 服务器中"无需额外参数即可调用"的工具，因此 --categoryExtensions 的工具暂不可用。排查技巧：卡住时先 chrome-devtools stop；DEBUG=* 环境变量输出详细日志。

六、进阶用法与作为浏览器 Subagent 集成

• 进阶场景：并发会话处理、持久化用户数据目录、连接已运行的 Chrome 实例而非新启动一个、Android 调试——见 Advanced Usage Guide；
• 全量工具清单：见 Tool Reference；
• 故障排查：遇到问题先看 Troubleshooting 指南；
• 设计原则：Design Principles 说明了项目的设计取舍，适合贡献代码前阅读（贡献流程见 CONTRIBUTING，变更记录见 CHANGELOG）。

README 还专门面向"正在开发 agentic 工具、想把浏览器 subagent 集成进产品"的开发者，建议基于 Chrome DevTools for agents 构建，并给出了 Gemini CLI browser agent 文档作为参考实现。结合仓库内的 skills/ 目录（包含 chrome-devtools、a11y-debugging、cookie-debugging、debug-optimize-lcp、memory-leak-debugging、troubleshooting 等技能）可以推断：这些 skills 与 MCP 工具配套分发，让 Agent 不仅"有工具"，还带有对应的专家操作指引——这正是插件安装方式（MCP + Skills）相比纯 MCP 安装的价值所在。

七、小结

chrome-devtools-mcp 的核心价值在于把 DevTools 的"手和眼"以标准 MCP 协议暴露给编码 Agent：性能 trace 与 Lighthouse 审计、网络/控制台/堆栈调试、基于 puppeteer 的可靠自动化。上手只需一段 JSON 配置；对上下文敏感的轻量场景用 --slim；对隐私敏感的环境用 --no-usage-statistics、--no-performance-crux 与 CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS 收口；脚本化、非 MCP 场景则用附带的 CLI。所有参数与行为的权威出处依次为 docs/configuration.md、docs/cli.md、docs/advanced-usage.md 与 src/index.ts、src/tools/tools.ts 中的实现。