mcp-chrome 安装与连接故障排查完全指南：doctor 诊断、report 报告与 Native Messaging 修复实战

本指南围绕开源仓库 mcp-chrome（Chrome MCP Server）中 docs/TROUBLESHOOTING.md 的核心内容展开，系统讲解当 Chrome 扩展点击 Connect 后连接失败时的完整排查链路：如何使用 mcp-chrome-bridge doctor 快速诊断与自动修复、如何用 mcp-chrome-bridge report 导出可提交的脱敏诊断报告，以及 manifest、执行权限、Node.js 路径、日志等常见故障根因与修复方法。读完本文，你将掌握从"连接失败"到"定位根因"再到"一键修复"的完整实战流程，并理解底层 Native Messaging 主机的运行机制。

一、快速诊断：一条命令定位问题

当扩展无法连接本地服务时，第一步永远是运行诊断工具，而不是盲目重装：

mcp-chrome-bridge doctor

该命令会依次检查安装完整性、manifest 文件、执行权限、Node.js 路径、端口配置与连通性六大类问题，并以 [OK] / [WARN] / [ERROR] 三色徽标逐条输出检查结果。若存在可自动修复的问题，还会给出对应的修复命令作为 "Next steps" 提示。

如果检查项全部通过，命令返回退出码 0；只要存在任何 ERROR 级别问题，退出码即为 1（详见 doctor.ts 中 return report.ok ? 0 : 1; 的实现），方便在 CI 或脚本中直接判断。

自动修复模式

mcp-chrome-bridge doctor --fix

--fix 会尝试自动修复常见问题，修复项（见 doctor.ts）包括：

修复项 ID	说明
logs	确保日志目录存在（递归创建用户可写目录）
node_path	将当前 Node.js 可执行路径写入 node_path.txt，供 run_host.sh / run_host.bat 使用
permissions	修复 Native Messaging 主机关键文件的执行权限
register	重新执行用户级 Native Messaging 主机注册（含 Windows 注册表项）

除此之外，doctor 还支持两个实用参数：

• --json：以 JSON 格式输出完整诊断结果，便于程序化解析；
• -b, --browser <browser>：指定目标浏览器，取值 chrome、chromium 或 all，默认自动检测本机已安装的浏览器（Windows 查注册表、macOS 查 /Applications、Linux 用 which 探测，见 browser-config.ts）。

二、导出诊断报告：高效提交 Issue

如果诊断结果未能直接解决问题，需要开 Issue 寻求帮助时，应导出完整的诊断报告，把环境信息一次性交给维护者：

# 将 Markdown 报告打印到终端（可直接复制粘贴到 GitHub Issue）
mcp-chrome-bridge report

# 写入文件
mcp-chrome-bridge report --output mcp-report.md

# 直接复制到剪贴板
mcp-chrome-bridge report --copy

report 命令在 doctor 检查结果之外，还会收集（见 report.ts）：

• 环境信息：操作系统类型与版本、Node.js 版本与可执行路径、当前工作目录；
• 包管理器：npm / pnpm 版本；
• 相关环境变量：CHROME_MCP_NODE_PATH、VOLTA_HOME、ASDF_DATA_DIR、FNM_DIR、NVM_DIR 等（这些正是 wrapper 脚本解析 Node.js 时的关键输入）；
• Manifest 快照：用户级与系统级清单文件的完整 JSON 内容；
• Wrapper 日志：按修改时间倒序选取最多 6 个日志文件，默认截取每个文件最后 200 行（见 report.ts）；
• Windows 注册表项（仅 Windows 平台）。

脱敏机制：默认隐藏敏感信息

报告默认开启脱敏（redaction），用户名、路径、Token 会被自动替换，例如：

• 本机用户名、home 目录路径替换为 <USER>、<HOME>、<USERPROFILE>；
• TOKEN、PASSWORD、SECRET、API_KEY、ACCESS_KEY、PRIVATE_KEY 等键值内容替换为 <REDACTED>；
• Authorization 头、Cookie、常见 API Header、邮箱地址均会被规则化脱敏（正则规则详见 report.ts）。

如果你确认报告内容不敏感、愿意共享完整路径，可关闭脱敏：

mcp-chrome-bridge report --no-redact

report 命令还支持以下参数，用于精确控制报告内容：

参数	说明	默认值
--json	以 JSON 而非 Markdown 输出	Markdown
--output <file>	写入指定文件（- 或 stdout 表示终端）	stdout
--copy	复制到剪贴板（macOS 用 pbcopy，Windows 用 clip，Linux 依次尝试 wl-copy/xclip/xsel）	关闭
--include-logs <mode>	日志包含模式：none / tail / full	tail
--log-lines <n>	tail 模式下的日志行数	200
--no-redact	禁用脱敏	开启脱敏

三、点击 Connect 后连接失败的逐步排查

以下排查步骤严格遵循 docs/TROUBLESHOOTING.md 的官方流程，从工具诊断到手动核验逐层深入。

步骤 1：先运行诊断工具

mcp-chrome-bridge doctor

诊断工具会检查安装情况、manifest、权限和 Node.js 路径四项核心内容，先让工具告诉你问题在哪，再进入人工核验。

步骤 2：确认 mcp-chrome-bridge 已全局安装

mcp-chrome-bridge -V

正常输出版本号即说明 CLI 已全局可用。若命令不存在，说明 npm 全局安装未完成，需要先完成安装。

步骤 3：核对 manifest 文件位置

Native Messaging 主机依赖浏览器在固定目录中查找 manifest 文件（名为 com.chromemcp.nativehost.json，来自 constant.ts 中的 HOST_NAME = 'com.chromemcp.nativehost'）。npm 包安装正确时，该文件应出现在以下位置：

• Windows：C:\Users\xxx\AppData\Roaming\Google\Chrome\NativeMessagingHosts
• macOS：/Users/xxx/Library/Application Support/Google/Chrome/NativeMessagingHosts
• Linux：~/.config/google-chrome/NativeMessagingHosts

（路径生成逻辑见 utils.ts，Chromium 浏览器的 manifest 位于对应的 Chromium/NativeMessagingHosts 或 ~/.config/chromium/NativeMessagingHosts 目录。）

manifest 的标准内容如下（生成逻辑见 utils.ts）：

{
  "name": "com.chromemcp.nativehost",
  "description": "Node.js Host for Browser Bridge Extension",
  "path": "/绝对路径/node_modules/mcp-chrome-bridge/dist/run_host.sh",
  "type": "stdio",
  "allowed_origins": ["chrome-extension://hbdgbgagpkpjffpklnamcljpakneikee/"]
}

其中 allowed_origins 必须是扩展 ID hbdgbgagpkpjffpklnamcljpakneikee（见 constant.ts），type 必须为 stdio，path 必须指向实际存在的 wrapper 脚本。doctor 会逐项校验这些字段的一致性（见 doctor.ts）：若 path 与实际安装位置不符、指向的文件不存在、或 allowed_origins 缺失扩展来源，均判定为 manifest.error。

若 manifest 缺失或内容失效，重新注册即可：

# 注册用户级 Native Messaging 主机（推荐，无需管理员权限）
mcp-chrome-bridge register

# 自动检测本机浏览器后注册
mcp-chrome-bridge register --detect

# 指定浏览器
mcp-chrome-bridge register --browser chrome

# 系统级安装（需要 sudo / 管理员权限）
sudo mcp-chrome-bridge register --system

register 命令会先写入 Node.js 路径文件，再写入 manifest；Windows 平台还会通过 reg add 写入 HKCU\Software\Google\Chrome\NativeMessagingHosts\<hostname> 注册表项并校验（见 utils.ts）。

步骤 4：检查执行权限

打开 manifest 的 path 字段即可确认安装目录。例如 macOS 下的安装路径为：

xxx/node_modules/mcp-chrome-bridge/dist/run_host.sh

若该脚本缺少执行权限，Chrome 将无法启动它。直接执行：

mcp-chrome-bridge fix-permissions

该命令会把 index.js、run_host.sh、cli.js（Windows 为 run_host.bat）统一设置为 755 权限（见 utils.ts）。doctor 在 Unix 平台也会单独检查 run_host.sh 是否可执行（canExecute 判定），并在权限不足时提示执行 mcp-chrome-bridge fix-permissions 或 chmod +x（见 doctor.ts）。

步骤 5：解决 Node.js 找不到的问题

如果你使用了 Node 版本管理器（nvm、volta、asdf、fnm），wrapper 脚本很可能找不到 Node.js——因为 Chrome 启动原生主机时继承的环境 PATH 与你 shell 中的 PATH 不同。此时设置环境变量：

export CHROME_MCP_NODE_PATH=/path/to/your/node

或者直接运行 mcp-chrome-bridge doctor --fix，将当前 Node 路径写入 node_path.txt 固化下来。

底层 wrapper 脚本的 Node.js 发现顺序非常完整（见 run_host.sh，doctor 中的 resolveNodeCandidate 与其逻辑镜像，见 doctor.ts）：

优先级	来源	说明
0	CHROME_MCP_NODE_PATH	环境变量显式覆盖，支持 ~ 展开与目录自动拼接 /node
1	node_path.txt	安装/--fix 时写入的安装期 Node 路径
1.5	相对路径	相对 dist/ 回退（Unix 为 ../../../bin/node，Windows 为 ..\..\..\node.exe）
2	Volta	$VOLTA_HOME/bin/node 或 ~/.volta/bin/node
3	asdf	~/.asdf/installs/nodejs/<最新版本>/bin/node
4	fnm	~/.fnm/node-versions/<最新版本>/installation/bin/node
5	NVM	先读 alias/default 指向的版本，再回退到最新已安装版本（仅 Unix）
6	常见路径	/opt/homebrew/bin/node、/usr/local/bin/node、/usr/bin/node（Windows 为 Program Files 等路径）
7	PATH	依次扫描 PATH 中的每个目录

doctor 不仅会报告 Node.js 解析结果，还会检查版本下限：Node.js 主版本必须 ≥ 20（见 doctor.ts 的 MIN_NODE_MAJOR_VERSION = 20），版本过旧会直接判定为 ERROR 并提示升级。

四、日志位置与解读

wrapper 日志存储在设计为用户可写的目录（避免安装目录无写权限导致日志缺失），这也是诊断报告能自动收集日志的前提：

• 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/）

（路径规则见 utils.ts；若用户目录不可写，wrapper 会回退到包内 logs/ 目录，见 run_host.sh。）

日志包含两类文件：

• native_host_wrapper_unix_<时间戳>.log：wrapper 脚本的启动与 Node.js 发现过程详情，记录了每一步搜索的候选路径、找到的 Node 可执行文件、以及最终执行命令；
• native_host_stderr_unix_<时间戳>.log：Node.js 进程的 stderr 输出，用于排查运行时错误。

wrapper 还内置了日志轮转：默认保留最近 5 份日志，更早的自动清理（见 run_host.sh）。在日志中重点关注：

• 是否出现 ERROR: Node.js executable not found! —— 说明第 5 步的 Node 解析全部失败；
• Node discovery source: 字段 —— 确认最终使用的是哪个来源的 Node；
• CHROME_MCP_NODE_PATH: <unset> —— 确认环境变量是否传入。

五、进阶：doctor 检查项与底层机制解读

mcp-chrome-bridge doctor 的完整检查体系（见 doctor.ts）包括以下 8 项，理解它们能让你在人工排查时有的放矢：

检查 ID	检查内容	判定逻辑
installation	安装信息	输出包名、版本、平台架构、Node 版本
host.files	主机文件完整性	run_host.sh / index.js / mcp/stdio-config.json 三者必须存在
host.permissions	执行权限（Unix）	run_host.sh 是否可执行
node	Node 可执行文件	解析结果 + node -v 可运行 + 主版本 ≥ 20
manifest.<browser>	各浏览器 manifest	存在性、JSON 可解析、name/type/path/allowed_origins 逐字段校验
registry.<browser>	Windows 注册表	注册表项存在且指向有效 manifest
port.config	端口配置	stdio-config.json 中的 URL 端口必须为 12306
connectivity	连通性	对 http://127.0.0.1:12306/ping 发起 GET，1.5 秒超时

其中端口一致性是容易忽视的故障点：期望端口固定为 12306（见 doctor.ts），若 stdio-config.json 中的端口被改动，doctor 会提示运行 mcp-chrome-bridge update-port 12306 恢复。该命令会重写配置文件中的 URL 端口（见 cli.ts）。

连通性检查则与扩展侧直接相关：如果 GET /ping 失败，doctor 会给出提示——"如果服务未运行，请先在扩展中点击 Connect 再重试"（见 doctor.ts），说明先点扩展上的 Connect 按钮、再运行 doctor 是连通性检查通过的前提顺序。

最后需要说明的是，以上所有命令与路径均来自当前仓库 app/native-server/src/scripts 目录下的真实实现（cli.ts、doctor.ts、report.ts、utils.ts、run_host.sh），不同版本的具体参数以你实际安装的 npm 包为准。掌握"先 doctor 定位、再 report 出报告、最后按修复建议执行"这一流程，即可快速解决绝大多数 mcp-chrome 扩展连接失败问题。