npx chrome-devtools-mcp：配置与排错

Chrome DevTools MCP 是给 coding agents 使用的浏览器运行时调试入口，官方仓库将其概括为“Chrome DevTools for coding agents”，最小启动方式是 npx chrome-devtools-mcp@latest。遇到“工具不可用”时，先把问题分成三层：客户端没有加载 MCP Server、Server 找不到或启动不了 Chrome、工具已经出现却没有拿到页面证据；按这个顺序排查，通常比反复重装浏览器更有效。

先在客户端实际读取的 MCP JSON 中加入以下 stdio 配置，确认问题究竟在配置格式、启动命令还是浏览器连接。下面结构适用于支持 mcpServers 和 type: "stdio" 的客户端；不同客户端只需要调整配置入口或字段格式。

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

如果客户端里看不到 chrome-devtools，先确认 JSON 写进了当前窗口、当前用户配置实际读取的文件，并检查括号、逗号、mcpServers 层级和字段名。此时客户端根本没有启动进程，因此先不要把时间花在 Chrome 路径上；修改配置后也需要让客户端重新加载，或者重启对应的 MCP Server。

配置字段没有错误却启动不了时，再检查 Node.js 与 Chrome。现有资料给出的运行门槛是 Node.js v20.19 以上和 Chrome 稳定版，具体最低版本及系统差异应以官方仓库当前的 Requirements 为准。下面的命令按实际系统选择，macOS 检查应用包内的二进制文件，Linux 则先从 PATH 中定位浏览器：

node -v
ls -la "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
which google-chrome || which chrome || which chromium

node -v 用来确认当前进程实际使用的 Node.js，而不是终端外另一个版本管理器中的版本。which 找不到 Chrome 时也可能是浏览器已安装但可执行文件没有进入 PATH，这并不等于机器上没有 Chrome。

在终端验证 npx 能获取并解析当前包：

npx chrome-devtools-mcp@latest --version
npx chrome-devtools-mcp@latest --help

两条命令能够正常返回后，只能说明包可以被当前 Node.js 启动；它仍不能证明客户端已经加载配置，也不能证明 Chrome 已连接。回到客户端确认 MCP Server 名称和工具列表是否出现，必要时重启客户端或 MCP Server，再处理浏览器连接。

Chrome 不在 PATH 时，把已经确认存在的浏览器二进制路径传给 --executablePath。路径必须指向实际可执行文件，并保持为一个完整字符串；不要依赖客户端启动目录下的相对路径。

"args": [
  "-y",
  "chrome-devtools-mcp@latest",
  "--executablePath=/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
]

如果 MCP Server 和工具已经出现，但 Chrome 启动或连接仍然失败，先拿到真实日志再判断原因。官方仓库当前列出的日志参数是 --logFile；如果本地 --help 显示了其他拼写，应以正在使用的版本为准，不要直接照抄旧配置中的 --log-file。

{
  "mcpServers": {
    "chrome-devtools": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "chrome-devtools-mcp@latest",
        "--logFile",
        "/absolute/path/chrome-devtools-mcp.log"
      ]
    }
  }
}

日志路径应使用客户端有权限写入的绝对路径。读日志时先找首个明确错误，再区分可执行文件路径、进程连接、缓存目录和沙箱问题；只有日志明确指向缓存或沙箱时才处理对应项，不应把清空浏览器数据或关闭沙箱当作通用修复。

npx 每次启动可能重新解析或下载软件包，因此首次启动较慢并不一定是故障。全局安装可以作为减少等待的可选方案，但它不会自动修复错误配置、Chrome 路径或连接问题。

连接恢复后，让代理先复现操作，再读取控制台，而不是只让它阅读源码。按首次出现顺序整理错误，通常更容易区分原始异常和后续连锁报错。

打开当前页面并复现问题，读取控制台日志，按首次出现顺序列出错误及其可能来源。

网络问题也要落到可核对的请求上。让代理列出失败或异常的 fetch、XHR 请求及其 URL、状态和时间信息，再与页面代码、请求参数交叉确认，避免把服务端错误误判成前端代码问题。

找出当前页面失败的 fetch/XHR 请求，列出 URL、状态和时间信息，并判断超时、连接还是服务端错误。

性能排查先建立基线，再定位耗时集中的阶段，最后回到对应的网络请求和控制台信息确认原因。单独给出“页面很慢”的结论没有多大价值，还应指出下一步需要核对的证据。

采集当前页面的加载性能数据，指出耗时最集中的阶段，并列出需要继续核对的网络请求。

修改后，在同一个页面上重新执行同一步操作，确认原来的控制台错误不再出现、失败请求已经消失，并将性能结果与修改前的基线对照，确认符合预期；如果其中一项仍失败，就回到对应层级继续查日志，而不是重新安装整个 MCP Server。