Chrome MCP Server 装完连不上？用 mcp-chrome-bridge doctor 三步定位，不用重装

【免费下载链接】mcp-chromeChrome MCP Server is a Chrome extension-based Model Context Protocol (MCP) server that exposes your Chrome browser functionality to AI assistants like Claude, enabling complex browser automation, content analysis, and semantic search.项目地址: https://gitcode.com/gh_mirrors/mc/mcp-chrome

mcp-chrome 的 Chrome MCP Server 依赖本地 Node.js 桥接进程与浏览器通信，装完后最常见的翻车点就是"扩展显示已连接，MCP 服务却起不来"。遇到这种情况先跑一遍mcp-chrome-bridge doctor，它能覆盖清单、权限、Node 解析等全部关键环节。读完这篇指南，你可以独立定位并修复大部分安装连接类问题。

先给结论：最短排障路径

赶时间的话直接照这三步走：

1. mcp-chrome-bridge doctor：定位是哪个检查项亮红灯
2. mcp-chrome-bridge doctor --fix：自动修复日志目录、Node 路径、权限并重新注册用户级宿主
3. 仍失败 →mcp-chrome-bridge report导出诊断报告，连同日志提交 Issue

三步走完还没解决，后面章节会带你逐症状深挖。

读懂 doctor 的输出：哪一项亮了红灯

doctor会逐项检查环境并输出带[OK]/[WARN]/[ERROR]的徽标，末尾附上 Next steps 建议。先搞清楚每项在查什么，红灯就不怕了：

两个实用参数：doctor --json输出结构化报告，doctor -b chrome|chromium|all限定浏览器范围（不指定时自动探测）。检查项的判定逻辑可以去 doctor.ts 对照源码验证。

症状 A：扩展已连接，MCP 服务却起不来

现象：扩展界面显示已连接，但 Agent 调用任何浏览器工具都超时或无响应。

原因：连接成功只说明 Chrome 通过 Native Messaging 拉起了宿主进程；服务起不来，大概率是清单文件缺失，或清单里的path字段指错了启动脚本。

先确认全局安装本身没问题：

mcp-chrome-bridge -V

你应该看到类似1.0.29的版本号。看不到命令，说明包没装好，先重新全局安装。

这一步就是确认 Native Messaging Host 清单是否就位。它必须放在浏览器专属目录里，文件名固定为com.chromemcp.nativehost.json：

• macOS：~/Library/Application Support/Google/Chrome/NativeMessagingHosts/
• Linux：~/.config/google-chrome/NativeMessagingHosts/
• Windows：%APPDATA%\Google\Chrome\NativeMessagingHosts\（Chromium 换Chromium目录）

文件内容长这样（字段生成逻辑见 utils.ts）：

{ "name": "com.chromemcp.nativehost", "type": "stdio", "path": "/Users/xxx/.../mcp-chrome-bridge/dist/run_host.sh", "allowed_origins": ["chrome-extension://hbdgbgagpkpjffpklnamcljpakneikee/"] }

四个字段一个都不能少：name必须与宿主名一致、type固定stdio、path必须指向真实存在且可执行的启动脚本、allowed_origins必须包含扩展 ID。manifest 的path指错了怎么办——答案通常是删掉手写过的旧清单，用官方命令重写：

mcp-chrome-bridge register

你应该看到 "Native Messaging host registered successfully!"。如果它猜不出你的浏览器，加-b chrome|chromium|all指定；需要覆盖旧文件加-d强制探测。想要系统级注册（需管理员/sudo，Windows 会同时写 HKLM）用-s。

预期结果：回扩展重新点 Connect，再跑一次doctor，manifest.*与connectivity两项转绿。还不行 → 转下面"排查到底了"看日志。

症状 B：权限报错 / 启动脚本不可执行

现象：清单在、Node 也找到了，但 Chrome 就是拉不起进程；或doctor的host.permissions报run_host.sh is not executable。

原因：npm 全局安装后文件有时会丢失可执行位，Chrome 无权代你补。

一条命令修复：

mcp-chrome-bridge fix-permissions

它在 Unix 下会给index.js、run_host.sh、cli.js统一设置 755 权限；Windows 下则移除只读属性并校验可读性。你应该看到逐项设置成功的输出。

预期结果：重跑doctor，host.permissions转绿，Connect 后服务正常起来。还不行 → 试试doctor --fix，它会顺带执行同一套权限修复。

症状 C：脚本找不到 node

现象：doctor的node项报Node.js executable not found by wrapper search order；wrapper 日志里 PATH 和终端里完全不一样。

原因：Chrome 拉启动脚本时用的是最小化环境，PATH 往往不带版本管理器（nvm、volta、asdf、fnm）注入的路径，终端里能跑不代表宿主里能跑。

两条修复路径，按持久性选：

1. 显式指定 Node（最高优先级，立即可用）：

export CHROME_MCP_NODE_PATH=/path/to/your/node

支持绝对路径或目录（目录会自动补/node），也支持~/展开。

2. 持久写入（推荐日常用）：

mcp-chrome-bridge doctor --fix

它把当前process.execPath写进 dist 目录的node_path.txt，启动脚本按第二优先级读取。

预期结果：重跑doctor，node项转绿，来源显示为CHROME_MCP_NODE_PATH或node_path.txt。版本过旧（主版本 < 20）则与查找无关，直接升级 Node 即可。

排查到底了：日志、report 与提交 Issue

上面都没解决，就到了看现场的时候。日志位置（都在用户可写目录，避免污染 npm 包目录）：

• macOS：~/Library/Logs/mcp-chrome-bridge/
• Windows：%LOCALAPPDATA%\mcp-chrome-bridge\logs\
• Linux：$XDG_STATE_HOME/mcp-chrome-bridge/logs/，未设置时回退~/.local/state/mcp-chrome-bridge/logs/

文件名带时间戳，分两类：native_host_wrapper_<平台>_<时间戳>.log记录启动时的 PATH 和完整 Node 查找过程；native_host_stderr_<平台>_<时间戳>.log记录 Node 进程自身报错。脚本内置轮转，各保留最近 5 份（run_host.sh 中LOG_RETENTION_COUNT=5），用户目录不可写时回退到包内dist/logs。

提 Issue 前先导出诊断报告——比口头描述错误信息有价值得多：

mcp-chrome-bridge report mcp-chrome-bridge report --output mcp-report.md mcp-chrome-bridge report --copy

报告默认输出 Markdown（--json可切换），包含环境信息、doctor 诊断、包装器日志和清单快照。默认开启脱敏：家目录、用户名、TOKEN/SECRET/API_KEY类变量、Authorization/Cookie 头、邮箱等都会被替换；确需完整路径排查时加--no-redact关闭。日志收集默认--include-logs tail（末尾 200 行、单文件截 256KB），可切none/full，配合--log-lines调行数。

提交 Issue 时附上：report生成的报告 + 日志目录里最新的 wrapper/stderr 两份日志。

两个边缘情况顺手说清：长时间空闲会导致会话超时，回扩展重新点 Connect 或重启宿主即可，无需重装；不同 Agent/模型调用工具的效果有差异，这属于模型能力匹配问题，不在安装排障范围内。

为什么 node 会"失踪"

run_host脚本被 Chrome 以最小化环境拉起，PATH 不可信，只能自己按固定顺序找 Node。理解这个优先级表，就能秒判故障点（完整逻辑见 run_host.sh）：

doctor的node检查完整复刻了这套顺序，所以它报"找不到"时，就是脚本真找不到——按症状 C 处理即可。

收尾：命令速查与预防建议

三条预防建议，能挡掉九成故障：

1. 务必全局安装（npm i -g mcp-chrome-bridge），装完先-V验证；
2. 装完先跑一次doctor建立基线，环境变化后第一时间重跑；
3. 用版本管理器管理 Node 时，显式设CHROME_MCP_NODE_PATH或跑一次doctor --fix落盘node_path.txt，别赌 PATH。

更多细节可参考仓库排障文档 TROUBLESHOOTING_zh.md。

【免费下载链接】mcp-chromeChrome MCP Server is a Chrome extension-based Model Context Protocol (MCP) server that exposes your Chrome browser functionality to AI assistants like Claude, enabling complex browser automation, content analysis, and semantic search.项目地址: https://gitcode.com/gh_mirrors/mc/mcp-chrome