Chrome DevTools MCP 配置使用说明

本文根据 ChromeDevTools/chrome-devtools-mcp README 整理，覆盖用途、配置方式、常用参数和安全注意事项。

chrome-devtools-mcp 是 Chrome DevTools 团队提供的 MCP Server。它把 Chrome DevTools 的能力暴露给支持 MCP 的 AI 编程助手，让 agent 可以打开页面、点击输入、查看控制台、分析网络请求、截图、跑 Lighthouse、录制 performance trace 等。

它适合把“浏览器里才能确认的问题”交给 agent 处理，例如：

复现前端交互问题。
查看 console error 和网络请求。
对页面进行截图检查。
跑性能 trace 并分析 Core Web Vitals。
在真实 Chrome 里验证页面是否能打开、按钮是否可用、表单是否能提交。

安装要求

README 中列出的基本要求：

Node.js LTS。
当前稳定版或更新版本的 Chrome。
npm。

默认启动方式使用 npx，不需要在项目里手动安装依赖。

如果运行环境是 Linux ARM64，需要额外注意：官方 Chrome for Testing 下载清单通常只提供 linux64，没有 linux-arm64。这类机器上可以安装发行版提供的 Chromium，并通过 --executablePath 显式指定浏览器路径。

Linux ARM64 安装 Chromium

以 Ubuntu 22.04 ARM64 为例，可以安装仓库里的 chromium-browser：

sudo apt-get update
sudo apt-get install -y chromium-browser

Ubuntu 上的 chromium-browser 通常是一个过渡包，会继续安装 Canonical 提供的 Chromium Snap。安装完成后先确认浏览器命令是否存在：

command -v chromium-browser
chromium-browser --version

正常情况下会看到类似结果：

/usr/bin/chromium-browser
Chromium 148.0.7778.167 snap

也可以检查 deb 包和 Snap 包状态：

dpkg -l chromium-browser
snap list chromium

dpkg -l chromium-browser 应该显示 ii 状态。如果安装过程在 Snap 下载阶段被中断，先不要重复开多个 apt 进程，可以查看 Snap 任务：

snap changes
snap watch <change-id>

等 Snap 安装结束后，如果 deb 包仍然处在半安装状态，可以修复一次：

sudo dpkg --configure -a
sudo apt-get install -y --reinstall chromium-browser

服务器或 root 环境下建议再做一个 headless smoke test：

chromium-browser --headless --no-sandbox --disable-gpu --dump-dom about:blank

只要能输出空白 HTML，并且退出码为 0，就说明 Chromium 可以被 MCP 作为 headless 浏览器后端启动。xdg-settings、VAAPI 或 DBus 相关 warning 在服务器环境里比较常见，通常不影响 headless 使用。

最小 MCP 配置

大多数 MCP 客户端都可以使用同一段基础配置：

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

chrome-devtools-mcp@latest 会让 MCP 客户端每次通过 npm 使用最新版本。适合想跟随官方更新的人；如果你希望稳定可复现，也可以固定具体版本号。

Codex 配置

在 Codex CLI 中，可以用命令添加：

codex mcp add chrome-devtools -- npx -y chrome-devtools-mcp@latest

也可以在配置里写成：

[mcp_servers.chrome-devtools]
command = "npx"
args = ["-y", "chrome-devtools-mcp@latest"]

如果 Codex 运行在 Linux ARM64 服务器上，并且使用 Ubuntu/Canonical 的 Chromium Snap，可以参考下面这段实测配置：

[mcp_servers.chrome-devtools]
command = "npx"
args = [
  "-y",
  "chrome-devtools-mcp@latest",
  "--executablePath=/usr/bin/chromium-browser",
  "--headless",
  "--isolated",
  "--chrome-arg=--no-sandbox",
  "--chrome-arg=--disable-setuid-sandbox",
  "--chrome-arg=--disable-gpu",
  "--no-usage-statistics",
  "--no-performance-crux",
]

这里的几个关键点：

--executablePath=/usr/bin/chromium-browser：不再让 MCP 默认寻找 /opt/google/chrome/chrome。
--headless：服务器环境不需要图形界面。
--isolated：每次使用临时 profile，避免污染默认浏览器数据。
--chrome-arg=--no-sandbox 和 --chrome-arg=--disable-setuid-sandbox：root 环境下启动 Chromium 常见需要。
--no-usage-statistics 和 --no-performance-crux：关闭使用统计和 CrUX 字段数据请求。

修改 ~/.codex/config.toml 后，需要重启 Codex，让 MCP 配置重新加载。

Windows 11 上，README 建议显式配置 Chrome 所需环境变量，并增加启动超时：

[mcp_servers.chrome-devtools]
command = "cmd"
args = [
  "/c",
  "npx",
  "-y",
  "chrome-devtools-mcp@latest",
]
env = { SystemRoot="C:\\Windows", PROGRAMFILES="C:\\Program Files" }
startup_timeout_ms = 20_000

轻量模式

如果只做基础浏览器任务，可以启用 --slim。它只暴露导航、脚本执行、截图等少量工具，减少工具面：

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

适合只需要打开页面、执行简单检查、截图，不需要完整 DevTools 分析能力的场景。

连接已有 Chrome

默认情况下，MCP Server 会自己启动一个 Chrome 实例。如果你希望复用已经登录的网站状态，或者 agent 运行在沙箱里但 Chrome 在外部运行，可以让它连接已有 Chrome。

常用配置：

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "-y",
        "chrome-devtools-mcp@latest",
        "--browserUrl=http://127.0.0.1:9222"
      ]
    }
  }
}

然后用 remote debugging port 启动 Chrome：

google-chrome \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/chrome-devtools-mcp-profile

Linux ARM64 上使用 Chromium 时，对应命令可以写成：

chromium-browser \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/chrome-devtools-mcp-profile

注意：remote debugging port 可以让本机其他程序控制浏览器。开启这个端口时，不要在同一个 Chrome profile 里打开敏感网站。

常用启动参数

参数	用途
`--headless`	无界面运行 Chrome，适合 CI 或服务器
`--viewport=1280x720`	设置初始窗口尺寸
`--channel=canary`	指定 Chrome channel，可选 `canary`、`dev`、`beta`、`stable`
`--executablePath=/path/to/chrome`	指定 Chrome 可执行文件路径
`--userDataDir=/path/to/profile`	指定 Chrome profile 目录
`--isolated`	使用临时 profile，避免污染默认 profile
`--browserUrl=http://127.0.0.1:9222`	连接已有 Chrome
`--logFile=/tmp/chrome-devtools-mcp.log`	写入调试日志
`--acceptInsecureCerts`	忽略自签名或过期证书错误，谨慎使用
`--experimentalPageIdRouting`	并发 agent 会话时按 pageId 路由页面级工具
`--chrome-arg=--no-sandbox`	额外传给 Chrome/Chromium 的启动参数

参数都放在 MCP 配置的 args 里，例如：

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "-y",
        "chrome-devtools-mcp@latest",
        "--headless",
        "--viewport=1440x900",
        "--isolated"
      ]
    }
  }
}

首次验证

README 建议的测试 prompt：

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

正常情况下，MCP 客户端会在需要浏览器工具时启动 Chrome，然后录制性能 trace 并返回分析结果。

如果你只想验证页面操作，可以让 agent 执行：

Open https://example.com, take a screenshot, and list console messages.

在 Codex 里，也可以直接说：

用 Chrome MCP 打开 http://localhost:3000，检查页面快照和控制台错误。

如果 mcp__chrome_devtools 仍然提示找不到 /opt/google/chrome/chrome，通常说明当前 Codex 会话还没有重新加载配置。重启 Codex 后再测试。

能提供哪些工具

README 自动生成的工具分组大致包括：

输入自动化：点击、拖拽、填表、上传文件、按键。
页面导航：打开新页面、切换页面、等待文本出现。
设备模拟：viewport、CPU、网络、地理位置、深色模式。
性能分析：开始/停止 trace，分析 performance insight。
网络检查：列出请求，查看请求和响应内容。
调试：控制台消息、截图、DOM snapshot、Lighthouse。
内存分析：heap snapshot 和对象保留关系。
扩展调试：安装、列出、重载、触发扩展动作。

日常前端排障最常用的是：

take_snapshot
take_screenshot
list_console_messages
list_network_requests
get_network_request
performance_start_trace
performance_stop_trace
lighthouse_audit

使用建议

把 Chrome DevTools MCP 当成“真实浏览器观察器”，而不是单纯的网页爬虫。

适合让 agent 做：

复现 UI bug。
检查错误日志。
看请求失败原因。
验证按钮、表单和导航。
录制性能 trace。
检查首屏是否空白、布局是否明显错位。

不建议让它接触：

已登录的隐私账号。
包含生产密钥的管理后台。
个人邮箱、支付、银行等敏感页面。
打开 remote debugging port 的主力浏览器 profile。

更安全的做法是使用 --isolated 或单独的 --user-data-dir，让 agent 操作临时 profile。

小结

Chrome DevTools MCP 的价值是把 DevTools 能力接给 AI agent。配置上最小只需要一段 mcpServers.chrome-devtools，复杂场景再按需加 --headless、--isolated、--browserUrl、--executablePath、--no-usage-statistics 等参数。

如果你经常让 agent 改前端代码，它非常值得接入：代码改完后，agent 可以直接打开页面、看 console、查 network、截图和做性能分析，验证会比只跑构建更接近真实用户环境。

安装要求​

Linux ARM64 安装 Chromium​

最小 MCP 配置​

Codex 配置​

轻量模式​

推荐安全参数​

连接已有 Chrome​

常用启动参数​

首次验证​

能提供哪些工具​

使用建议​

小结​