引言

在日常开发中，很多人希望通过 codex MCP 与 chrome-devtools-mcp 来实现浏览器 DevTools 的远程调试与自动化控制。然而在 Windows 环境下，许多开发者遇到了相同的错误：

  • MCP client for 'chrome-devtools' failed to start: program not found
  • MCP client for 'chrome-devtools' failed to start: request timed out

这些问题看似复杂，其实是路径、执行环境与 Chrome 启动方式的问题。本文将带你完整复盘排查过程，并总结出可复现的解决方案。

问题复盘

环境信息

  • 系统：Windows Server / Windows 10/11
  • Node.js 路径：E:\instal\nodejs\
  • 安装方式：npx chrome-devtools-mcp@latest
  • codex 注册方式：codex mcp add chrome-devtools -- npx chrome-devtools-mcp@latest

典型症状

  1. codex mcp list 显示：

    Name             Command              Args  Env
chrome-devtools  chrome-devtools-mcp  -     -

  2. where chrome-devtools-mcp 无返回值，但 Get-Command 显示：

    ExternalScript  chrome-devtools-mcp.ps1  E:\instal\nodejs\chrome-devtools-mcp.ps1

  3. 手动运行 node index.js 仅打印帮助信息，而不是进入监听状态。

  4. Get-NetTCPConnection -State Listen 检查端口 9223 无监听进程。

根本原因

  1. Windows 下 npx 安装的可执行文件没有生成 .cmd 或 .exe shim，而是一个 .ps1 脚本，导致 codex 调用失败。
  2. MCP client 依赖 Chrome 的 remote-debugging-port，若 Chrome 没有用该参数启动，MCP 会直接退出。
  3. Chrome 在 Windows 下默认只安装在 C:\Program Files\Google\Chrome\Application\chrome.exe，而 devtools-mcp 固定查找路径是 C:\Users\<User>\AppData\Local\Google\Chrome\Application\chrome.exe。
  4. 没有监听端口 → MCP client 没有真正进入服务模式，codex 自然超时。

解决方案总览

  1. 全局安装 npm install -g chrome-devtools-mcp，确保 chrome-devtools-mcp.cmd 存在于 PATH。
  2. 创建 Windows wrapper，用 .cmd 调用 .ps1 或 Node.js 脚本。
  3. 强制 codex 调用 PowerShell 执行 .ps1。
  4. 启动 Chrome 并启用 remote-debugging-port。
  5. 修复 Chrome 查找路径问题（最终解决方案）。

实战步骤

步骤一：预检环境

node -v
npm -v
npx --version
codex mcp list
Get-Command chrome-devtools-mcp
where chrome-devtools-mcp

步骤二：全局安装 chrome-devtools-mcp（推荐）

npm install -g chrome-devtools-mcp
where chrome-devtools-mcp
chrome-devtools-mcp --help

若能找到 .cmd 文件且能正常执行 --help，说明 shim 正常。

步骤三：Chrome 启动参数

Chrome 必须以 remote-debugging 方式启动：

Start-Process "C:\Program Files\Google\Chrome\Application\chrome.exe" -- '--remote-debugging-port=9222' '--user-data-dir=C:\chrome-debug-profile'
Test-NetConnection -ComputerName 127.0.0.1 -Port 9222

步骤四：启动 MCP client

node "E:\instal\nodejs\node_modules\chrome-devtools-mcp\build\src\index.js" start --host 127.0.0.1 --port 9223 --chrome-port 9222 --verbose

验证：

Get-NetTCPConnection -State Listen | Where-Object { $_.LocalPort -eq 9223 }

步骤五（最终修复）：修复 Chrome 查找路径

chrome-devtools-mcp 固定查找路径是：

C:\Users\Administrator\AppData\Local\Google\Chrome\Application\chrome.exe

但实际 Chrome 安装在：

C:\Program Files\Google\Chrome\Application\chrome.exe

解决方法：创建符号链接

New-Item -ItemType SymbolicLink `
   -Path "$env:LOCALAPPDATA\Google\Chrome\Application\chrome.exe" `
   -Target "C:\Program Files\Google\Chrome\Application\chrome.exe"

另外，在仓库根目录下创建一个指向 C:\Users\Administrator\AppData\Local 的目录联接：

mklink /D "<repo-root>\\undefined" "C:\Users\Administrator\AppData\Local"

这样 DevTools 就能按固定逻辑找到 chrome.exe。

日志与错误解析

  • program not found → shim 缺失，需全局安装或创建 wrapper。
  • request timed out → MCP client 没有监听端口，检查 Chrome 是否 remote-debugging 启动。
  • NativeCommandError → PowerShell 将 stdout 视为错误，实际 MCP 正在运行。

codex 整合最佳实践

  1. 用 .cmd shim 或符号链接保证 chrome-devtools-mcp 可执行。

  2. 在 codex 注册时指向正确可执行：

    codex mcp remove chrome-devtools
codex mcp add chrome-devtools -- chrome-devtools-mcp

  3. 启动 Chrome 时总是加上 --remote-debugging-port 参数。

  4. 日志重定向，方便排查：

    chrome-devtools-mcp start --port 9223 > C:\temp\mcp.log 2>&1

常见 FAQ

  • Q: where chrome-devtools-mcp 没有返回？
    A: 全局安装或在 %APPDATA%\\npm 创建 .cmd wrapper。

  • Q: MCP client 启动但 codex 仍超时？
    A: 检查是否有监听端口 9223，确认 Chrome 是否 remote-debugging 启动。

  • Q: 为什么需要符号链接？
    A: 因为 devtools-mcp 在 Windows 下写死了查找路径，必须让它找到 Chrome 可执行文件。

总结

本文完整复盘了 Windows 下 codex mcp chrome-devtools 无法启动的问题，从 shim 缺失、Chrome 未 remote-debugging 到 路径查找失败。最终解决方案是：

  1. 全局安装 chrome-devtools-mcp 确保可执行。
  2. 启动 Chrome 并开放 remote-debugging。
  3. 创建符号链接，保证 devtools-mcp 能找到 chrome.exe。

执行这三步后，codex mcp 与 chrome-devtools-mcp 可以稳定运行，不再出现超时或找不到程序的错误。

附录：命令速查表

# 全局安装
npm install -g chrome-devtools-mcp

# 启动 Chrome
Start-Process "C:\Program Files\Google\Chrome\Application\chrome.exe" -- '--remote-debugging-port=9222' '--user-data-dir=C:\chrome-debug-profile'

# 启动 MCP client
chrome-devtools-mcp start --port 9223

# 创建符号链接
New-Item -ItemType SymbolicLink `
   -Path "$env:LOCALAPPDATA\Google\Chrome\Application\chrome.exe" `
   -Target "C:\Program Files\Google\Chrome\Application\chrome.exe"

# 验证端口监听
Get-NetTCPConnection -State Listen | Where-Object { $_.LocalPort -eq 9223 }