如何跨三平台稳定部署 Chrome MCP Server 的 Native Messaging 主机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你在 Chrome 扩展弹窗里点下 Connect状态却迟迟停在 unknown控制台只留下一句含糊的 “Native host has exited”。多数时候这并非扩展的错而是 Chrome MCP Server 的本地桥接主机 mcp-chrome-bridge即 Native Messaging 主机没有注册正确。本文按“装 → 注册 → 体检 → 自救”的任务顺序推进所有关键结论都能回溯到仓库app/native-server/下的源码文件。注册成功长什么样连接判据与两端对应关系先给结论注册成功的唯一判据是“弹窗状态变为 connected且本地 HTTP 服务在 12306 端口有响应”此前的一切动作都只是在铺垫。这条连接横跨两端拆开看很清晰扩展端Connect 按钮会向 background 发送connectNative消息最终由 background 执行chrome.runtime.connectNative(com.chromemcp.nativehost)见 app/chrome-extension/entrypoints/background/native-host.ts。主机端Chrome 依据主机名找到清单用path指向的程序建立 stdio 通道。app/native-server/src/native-messaging-host.ts 按“4 字节小端长度头 JSON 正文”的帧格式解析消息收到start指令后在指定端口启动 HTTP 服务缺省 12306。判定两端是否都就绪用三组信号弹窗显示 connected——说明扩展收到了SERVER_STARTED确认消息而不是仅仅拿到了 PortGET http://127.0.0.1:12306/ping返回 200——主机端服务真的在监听fastify 的/ping路由MCP 客户端配置的 URL 指向http://127.0.0.1:12306/mcp——该值写在dist/mcp/stdio-config.json端口常量NATIVE_SERVER_PORT 12306定义在 app/native-server/src/constant/index.ts。另有一条安全边界值得留意清单的allowed_origins只放行chrome-extension://hbdgbgagpkpjffpklnamcljpakneikee/也就是说只有 Chrome MCP Server 这个扩展能连上该主机其他扩展会被 Chrome 直接拒绝。可验证动作点 Connect 后执行curl http://127.0.0.1:12306/ping返回 200 即全链路打通。动手前自检两条红线与一张权限决策表先给结论开工前确认 Node 版本与运行身份这两件事能避开绝大多数后续故障。两条红线Node.js 必须 ≥ 20。app/native-server/package.json 的engines.node写着20.0.0doctor 也会把主版本低于 20 的 Node 直接判为 ERROR。⚠️ 原生模块对 ABI 敏感。依赖里的better-sqlite3按特定 Node 版本编译绑定拉起主机的 Node 若与安装时不是同一个NODE_MODULE_VERSION不匹配会让进程直接崩溃。这正是主机不直接由 Node 启动、而套一层 run_host 包装脚本的原因末节详述。一个容易忽略的设计取向package.json 声明preferGlobal: true设计上以全局安装为主局部安装不会自动注册。身份与工具链的 if-then 决策你的情况该怎么做node -v主版本 20先升级 Node再谈其他普通用户 npm install -g用户级注册足够无需 sudo用 sudo / root 安装自动注册会被跳过下节细说装完以普通用户补跑mcp-chrome-bridge register多用户机器、想让所有用户共用系统级sudo mcp-chrome-bridge register --system用 pnpm 全局安装能自动识别但 pnpm 可能不保留可执行位装完建议mcp-chrome-bridge doctor --fix兜底可验证动作跑一遍node -v npm -v确认主版本 ≥ 20 且记录好当前 Node 的安装方式npm / nvm / asdf 等。一条命令部署npm install -g 背后藏了哪些动作先给结论npm install -g mcp-chrome-bridge只是一行但 postinstall 钩子里藏着 5 个动作执行顺序与跳过条件都由 app/native-server/src/scripts/postinstall.ts 控制。源码里的执行序列ensureExecutionPermissions()Unix 下给index.js、run_host.sh、cli.js三个文件设置 755Windows 下则移除对应三文件index.js、run_host.bat、cli.js的只读属性并验证可读。writeNodePathFile()把当前 Node 可执行文件绝对路径写入dist/node_path.txt。package.json 的files字段特意排除了!dist/node_path.txt保证运行期读到的一定是本机安装那一刻写下的值。detectGlobalInstall()兼容 npmnpm_config_global与 pnpmPNPM_HOME、~/.local/share/pnpm/global/等目录特征Windows 下另有%APPDATA%\pnpm\一类模式。isRunningElevated()若 UID 为 0脚本会主动跳过自动注册并打印说明——因为用户级清单会落进 root 的主目录普通账户根本看不见。其余情况执行用户级注册失败则建议系统级并打印手动指引。对应到 if-then 分支就是安装身份与范围postinstall 行为普通用户 全局自动用户级注册一步到位root / 管理员 全局修权限、写 node_path.txt跳过注册打印mcp-chrome-bridge register普通用户或sudo mcp-chrome-bridge register --system两条指引局部安装没带 -g只修权限、打印npx mcp-chrome-bridge register一类手动指引用户级注册失败提示改走mcp-chrome-bridge register --system可验证动作执行cat $(npm root -g)/mcp-chrome-bridge/dist/node_path.txt输出应当是你 Node 的绝对路径。三平台注册矩阵用户级与系统级路径速查先给结论注册的产物就一份 manifest.jsonWindows 外加注册表项路径由 app/native-server/src/scripts/utils.ts 与 app/native-server/src/scripts/browser-config.ts 按平台和级别算出。清单内容由createManifestContent()组装字段值全部来自 app/native-server/src/scripts/constant.ts 的常量{ name: com.chromemcp.nativehost, description: Node.js Host for Browser Bridge Extension, path: run_host.sh 或 run_host.bat 的绝对路径, type: stdio, allowed_origins: [chrome-extension://hbdgbgagpkpjffpklnamcljpakneikee/] }注意path指向的是包装脚本而不是 Node 本身Node 的挑选被推迟到了 run_host 那一层见末节。Chrome 的路径矩阵平台用户级无需管理员系统级需管理员Windows%APPDATA%\Google\Chrome\NativeMessagingHosts\com.chromemcp.nativehost.json%ProgramFiles%\Google\Chrome\NativeMessagingHosts\com.chromemcp.nativehost.jsonmacOS~/Library/Application Support/Google/Chrome/NativeMessagingHosts/...json/Library/Google/Chrome/NativeMessagingHosts/...jsonLinux~/.config/google-chrome/NativeMessagingHosts/...json/etc/opt/chrome/native-messaging-hosts/...jsonChromium 只是把浏览器目录名换掉Linux 用户级~/.config/chromium/NativeMessagingHosts/、系统级/etc/chromium/native-messaging-hosts/macOS 用户级~/Library/Application Support/Chromium/NativeMessagingHosts/、系统级/Library/Application Support/Chromium/NativeMessagingHosts/。Windows 上 Chromium 则走注册表键用户级HKCU\Software\Chromium\NativeMessagingHosts\com.chromemcp.nativehost系统级HKLM\Software\Chromium\NativeMessagingHosts\com.chromemcp.nativehost。两个实现细节Windows 是双写的。除了清单文件还会执行reg add 键 /ve /t REG_SZ /d 清单路径 /f随后用reg query 键 /ve回读由verifyWindowsRegistryEntry()比对值与写入路径是否一致。系统级是两阶段。registerWithElevatedPermissions()先把清单落到系统临时目录os.tmpdir()已提权时再复制到目标并chmod 644非 Windows未提权时直接打印确切的 sudo / 管理员命令并抛错。CLI 的分支逻辑见 app/native-server/src/cli.ts 的 register 命令先写 node_path.txt随后若带--system或检测到已提权Unix 看 UIDWindows 借助is-admin包就走系统级否则走用户级失败时依次给出sudo mcp-chrome-bridge register与mcp-chrome-bridge register --system两条补救。浏览器指向--browser chrome|chromium|all显式指定--detect走detectInstalledBrowsers()探测——Windows 查HKLM\SOFTWARE\Google\Chrome与HKLM\SOFTWARE\ChromiummacOS 看/Applications/下的应用目录Linux 用which google-chrome / google-chrome-stable / chromium / chromium-browser。一个都没探到时默认 Chrome 与 Chromium 都注册。场景命令默认当前用户够用mcp-chrome-bridge register需要系统级sudo mcp-chrome-bridge register --systemWindows 以管理员终端直接跑register --system只用 Chromiummcp-chrome-bridge register --browser chromium不确定机器上有什么mcp-chrome-bridge register --detect可验证动作打开你平台对应的用户级清单文件核对name、type、path、allowed_origins四个字段并确认path指向的文件真实存在。一条命令体检doctor 的逐项检查与 --fix 自愈先给结论mcp-chrome-bridge doctor把 Chrome 会做的校验全部预演了一遍且每项不通过都会附上下一步该敲的命令。实现见 app/native-server/src/scripts/doctor.ts。检查项清单每项给出 OK / WARN / ERROR检查 ID检查内容installation包名版本、平台架构、当前 Node 版本host.filesrun_host.sh/.bat、index.js、mcp/stdio-config.json三件套是否齐全host.permissionsUnix 下run_host.sh是否带可执行位node按与 run_host 相同的顺序解析 Node 可执行文件并校验node -v主版本 ≥ 20manifest.browser清单存在且 JSON 可解析name/type/allowed_origins与预期一致path等于当前安装的包装脚本且目标存在registry.browser仅 Windows注册表项存在值指向真实存在的清单port.config/port.constantstdio-config.json里 URL 的端口是否为 12306并与NATIVE_SERVER_PORT常量一致connectivity对GET /ping发起 1.5 秒超时的请求logs日志目录是否已创建两个实战要点node项的解析函数resolveNodeCandidate()完整镜像了 run_host 脚本的优先级doctor 的输出等于提前告诉你 Chrome 实际会选中哪个 Node。若 node_path.txt 缺失或失效、靠别的通道才找到 Node会给 WARN修复建议就是doctor --fix或手动设CHROME_MCP_NODE_PATH。connectivity失败时只是 WARN 而非 ERROR因为 HTTP 服务要到扩展连上之后才启动。报告里的提示语也正是先回扩展点 Connect再重跑 doctor。--fix按固定顺序执行四个修复动作创建日志目录 → 重写node_path.txt→ 修可执行权限 → 重新做用户级注册逐项汇报成败。--json输出结构化报告供脚本消费-b chrome|chromium|all收窄目标浏览器。退出码 0 / 1 对应“无 ERROR / 有 ERROR”方便接入 CI。要提 issue 时用report命令导出脱敏报告默认 Markdown--json切 JSON--include-logs tail|full附带包装脚本日志tail 默认 200 行--copy直接进剪贴板。可验证动作跑mcp-chrome-bridge doctor要求每项都是[OK]出现红项就照它打印的 “Next steps” 执行。症状自救手册按报错文本查动作先给结论绝大多数报错都能归进权限、Node 路径、Node 版本、注册表、服务未启动五类原因每类都有固定首选手法。症状macOS / Linux 报Permission denied或Native host has exited。 原因run_host.sh丢了可执行位pnpm 安装、解压、手动拷贝都是高危操作。 动作mcp-chrome-bridge fix-permissions内部调用ensureExecutionPermissions()给三个文件补 755或doctor --fix手动则为chmod x dist/run_host.sh。症状包装日志出现ERROR: Node.js executable not found!。 原因run_host 的九级定位全部落空。 动作设CHROME_MCP_NODE_PATH/绝对路径/node显式覆盖或mcp-chrome-bridge doctor --fix重写 node_path.txt。症状doctor 的node项报 too oldrequires 20.0.0。 原因定位到的 Node 主版本低于 20。 动作升级 Node 后跑doctor --fix重新记录新路径再回扩展点 Connect。症状Windows 报Access denied或文件只读。 原因文件被标只读或缺少管理权限。 动作mcp-chrome-bridge fix-permissions会移除只读属性并验证可读仍不行就卸载重装npm uninstall -g mcp-chrome-bridge后重新npm install -g再补fix-permissions。症状doctor 的registry项报 not found / inconsistent仅 Windows。 原因注册表项缺失或值指向旧清单。 动作reg query HKCU\Software\Google\Chrome\NativeMessagingHosts\com.chromemcp.nativehost /ve看实际值再用mcp-chrome-bridge register --browser chrome重写。症状doctor 全绿MCP 客户端却连不上。 原因本地服务还没被拉起——HTTP 服务依赖扩展的 Connect 触发。 动作弹窗点 Connect → 等 connected →curl http://127.0.0.1:12306/ping→ 重跑 doctor。 仍无解时包装日志是最后一份证据。它记录每次 Chrome 拉起主机的完整现场平台日志目录文件命名macOS~/Library/Logs/mcp-chrome-bridgenative_host_wrapper_unix_时间戳.logLinux${XDG_STATE_HOME:-~/.local/state}/mcp-chrome-bridge/logs同上Windows%LOCALAPPDATA%\mcp-chrome-bridge\logsnative_host_wrapper_windows_时间戳.log两个易踩的坑用户目录不可写时run_host 会退回把日志写进包内dist/logs主机进程的 stderr 另有对应的native_host_stderr_*.log崩溃堆栈通常在那里。可验证动作打开最新一份包装日志确认 “Node discovery source” 与 “Node version” 两行内容符合预期。底层机制run_host 的九级 Node 定位与日志轮转先给结论run_host 包装脚本的全部职责是“用和安装时同一个 Node 去执行 index.js”它靠一套九级定位算法完成这件事。见 app/native-server/src/scripts/run_host.shWindows 版 run_host.bat 逻辑同构第 5 级换成where node.exe且没有 NVM 分支。为什么不直接由 Node 启动Chrome 拉起 native host 时给的是它自己的干净环境你 shell 里的 PATH、nvm 钩子统统不存在。若依赖“PATH 里有 Node”很可能拿到另一个版本原生模块随即加载失败。所以清单path指向包装脚本把 Node 的挑选权收进脚本。sh 版的优先级表每一级失败才落到下一级优先级来源说明0CHROME_MCP_NODE_PATH环境变量显式覆盖可填目录自动补/node1node_path.txt安装 / 注册时写入版本锁定的核心1.5dist 上溯三级的bin/node相对路径兜底2Volta$VOLTA_HOME/bin/node缺省~/.volta3asdfinstalls/nodejs下版本号最大的目录4fnmnode-versions下版本号最大的目录5NVM先读alias/default再退回最新版本6常见路径/opt/homebrew/bin/node、/usr/local/bin/node、/usr/bin/node7command -v node当前 shell 可见性8PATH 扫描逐段遍历 PATH命中之后脚本把选中 Node 的 bin 目录塞到PATH头部供子进程使用把CHROME_MCP_NODE_PATH、VOLTA_HOME、ASDF_DATA_DIR、FNM_DIR、NVM_DIR及最终选中的版本写入日志最后exec node index.jsstderr 单独落到native_host_stderr_*.log。日志轮转run_host.shENABLE_LOG_ROTATIONtrue且LOG_RETENTION_COUNT5每次启动按时间删除第 5 份之外的 wrapper 与 stderr 旧日志避免长期运行堆满目录。逃生通道若九级全部失败日志会直接给出两条修法——设置CHROME_MCP_NODE_PATH或跑mcp-chrome-bridge doctor --fix。由于 doctor 的resolveNodeCandidate()与这套优先级完全镜像你随时能用它预演 Chrome 会做出同样的选择。可验证动作在包装日志里找到 “Node discovery source” 行确认它是node_path.txt而不是PATH——这代表版本锁定真正生效。✅【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考