三大平台装好 Chrome MCP 本地主机只需几步：mcp-chrome-bridge 安装与注册避坑实战指南
【免费下载链接】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
在扩展里点了 Connect，却弹出一句Native host has exited；或者 Chrome 压根找不到com.chromemcp.nativehost这个清单文件——这两个报错，基本都指向同一件事：Chrome MCP Server 的本地 Native Messaging 主机没装好、没注册成功。
Chrome 扩展跑在浏览器沙箱里，碰不到本地文件和 Node.js 进程。为了让 AI 助手（比如 Claude）借助 Chrome MCP Server 获得浏览器自动化、内容分析、语义搜索能力，扩展必须通过 Native Messaging 协议以stdio方式拉起一个本地进程来通信。这个进程就是mcp-chrome-bridge：一条 npm 包形式的本地主机，装在机器上，再把"清单 + 启动脚本"注册给浏览器，扩展端的chrome.runtime.connectNative就能接通它。
好消息是：注册这件事，90% 的情况下一条命令就能自动完成。下面我们把"装 → 注册 → 验证 → 排错"这条链路拆成可跳读的几节，按你的问题直接定位。
30 秒速览：它是什么，装完得到什么
这一节帮你建立心智模型，先知道装完之后系统里多了哪些东西。
| 问题 | 答案 |
|---|---|
| 它是什么 | mcp-chrome-bridge：Chrome MCP Server 的本地 Native Messaging 主机（Node.js 实现），负责在扩展和本机服务之间做 stdio 双向通信 |
| 装完得到什么 | 全局可用的三个命令：mcp-chrome-bridge（注册/诊断管理入口）、chrome-mcp-bridge（同入口别名）、mcp-chrome-stdio（MCP stdio 服务端） |
| 关键产物 1：清单文件 | com.chromemcp.nativehost.json，告诉浏览器"去哪里、用什么命令拉起主机" |
| 关键产物 2：启动脚本 | run_host.sh（macOS/Linux）或run_host.bat（Windows），负责锁定 Node 版本并启动index.js |
| 关键产物 3：注册表项（仅 Windows） | HKCU\Software\Google\Chrome\NativeMessagingHosts\com.chromemcp.nativehost等键，指向清单文件 |
| 运行前提 | Node.js >= 20.0.0；依赖中含better-sqlite3原生模块，对 Node ABI 敏感，这正是"锁 Node 版本"存在的原因 |
一条命令上手：安装并自动完成用户级注册
这一节给你最小可运行路径，装完即可用doctor验证。
先确认环境：
node -v && npm -vNode 版本必须 >= 20，否则后面doctor会直接报 ERROR。
然后全局安装：
npm install -g mcp-chrome-bridge这一条命令背后，postinstall钩子（src/scripts/postinstall.ts）会替你做完四件事：
- 修复执行权限：给
index.js、run_host.sh（Windows 为run_host.bat）、cli.js设置 755 权限（Windows 下改为移除只读属性并验证可读性）； - 写入 Node 路径：把当前
process.execPath写进node_path.txt，供启动脚本锁定 Node 版本； - 检测安装方式：区分 npm 全局、pnpm 全局（
PNPM_HOME、~/.local/share/pnpm/global/等特征）与局部安装。局部安装不会自动注册，只会打印npx mcp-chrome-bridge register的手动指引； - 尝试用户级注册：成功则收工；失败则提示你改跑
mcp-chrome-bridge register --system。
一个容易踩的坑：如果你用sudo安装，脚本检测到 UID 0 后会故意跳过自动注册——否则清单会写进 root 的主目录，你的普通账户根本用不上。它会提示你装完后以普通用户身份执行：
mcp-chrome-bridge register装完立刻跑一次体检（下一节详述）：
mcp-chrome-bridge doctor三种注册场景：用户级、系统级、多浏览器
这一节回答"我到底该用哪种注册方式"，以及 Chrome 之外的 Chromium 怎么办。
场景一：用户级注册（默认，推荐）
无需管理员权限，写入当前用户目录下的清单文件：
| 平台 | Chrome 清单位置 |
|---|---|
| Windows | %APPDATA%\Google\Chrome\NativeMessagingHosts\com.chromemcp.nativehost.json |
| macOS | ~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.chromemcp.nativehost.json |
| Linux | ~/.config/google-chrome/NativeMessagingHosts/com.chromemcp.nativehost.json |
自动注册失败时手动补一次：
mcp-chrome-bridge registerWindows 上还会额外创建用户级注册表项：HKCU\Software\Google\Chrome\NativeMessagingHosts\com.chromemcp.nativehost，默认值指向清单路径，并回读校验一致性（实现见 src/scripts/utils.ts）。
场景二：系统级注册（权限不足时的两条路）
需要管理员/root 权限，写入系统目录，对所有用户生效：
| 平台 | Chrome 系统级清单位置 |
|---|---|
| Windows | %ProgramFiles%\Google\Chrome\NativeMessagingHosts\ |
| macOS | /Library/Google/Chrome/NativeMessagingHosts/ |
| Linux | /etc/opt/chrome/native-messaging-hosts/ |
两种等价玩法：
# 方式 A：显式 --system（推荐） sudo mcp-chrome-bridge register --system # macOS/Linux mcp-chrome-bridge register --system # Windows（管理员终端） # 方式 B：直接以提权身份跑 sudo mcp-chrome-bridge register # macOS/Linux mcp-chrome-bridge register # Windows（管理员终端）注意一个 CLI 细节（src/cli.ts）：它会自动检测当前是否已提权（Unix 看 UID 0，Windows 用is-admin）。只要已提权，即使不带--system也会走系统级分支——所以"管理员终端里直接 register"和"带--system"结果一样。用户级注册失败时，CLI 会明确打印上面两种补救命令。
场景三：多浏览器注册（Chrome + Chromium）
默认只针对 Chrome。注册命令支持--browser与--detect两个参数来显式控制目标（src/scripts/browser-config.ts）：
mcp-chrome-bridge register --browser chromium # 只注册 Chromium mcp-chrome-bridge register --browser all # Chrome + Chromium 都注册 mcp-chrome-bridge register --detect # 自动探测已安装浏览器探测逻辑：Windows 查注册表HKLM\SOFTWARE\Google\Chrome与HKLM\SOFTWARE\Chromium；macOS 检查/Applications/下是否有对应.app；Linux 用which google-chrome/google-chrome-stable/chromium/chromium-browser。一个都没探测到时，默认两者都注册。Chromium 在 Linux 的用户级/系统级位置分别是~/.config/chromium/NativeMessagingHosts/和/etc/chromium/native-messaging-hosts/，Windows 下对应HKCU/HKLM\Software\Chromium\NativeMessagingHosts\注册表键。
注册到底写了什么：manifest、run_host 与安全边界
这一节拆开注册的三个核心产物，看懂它们，绝大多数"注册了却不生效"的问题都能自行定位。
manifest.json：五个字段定生死
清单内容全部由 src/scripts/utils.ts 的createManifestContent()生成，字段与 src/scripts/constant.ts 的常量一一对应：
| 字段 | 值 | 作用 |
|---|---|---|
name | com.chromemcp.nativehost | Chrome 靠它定位清单 |
description | Node.js Host for Browser Bridge Extension | 主机描述 |
path | run_host.sh（Windows 为run_host.bat）的绝对路径 | 浏览器实际拉起的入口 |
type | stdio | 固定为 stdio 通信 |
allowed_origins | ["chrome-extension://hbdgbgagpkpjffpklnamcljpakneikee/"] | 白名单：只有这个扩展 ID 能连上主机 |
清单 JSON 以 2 空格缩进写入（JSON.stringify(manifest, null, 2)）。核对安装时，重点看这四个：name/type/path/allowed_origins，path必须真实存在且指向当前安装目录下的包装脚本。
run_host 包装脚本：为什么 path 不直接指向 index.js
清单path指向的不是 Node 脚本本身，而是 run_host.sh。原因很实际：better-sqlite3这类原生模块绑定 Node ABI 版本，如果 Chrome 拿系统 PATH 里"另一个版本"的 Node 来拉起主机，NODE_MODULE_VERSION不匹配直接崩。
所以 run_host 内置了一套多优先级 Node 发现算法（run_host.bat 在 Windows 上做同样逻辑）：
| 优先级 | 来源 |
|---|---|
| 0 | 环境变量CHROME_MCP_NODE_PATH（显式覆盖，最高优先） |
| 1 | node_path.txt（注册时写入的 Node 绝对路径） |
| 1.5 | 相对路径回退（dist 上溯三级bin/node） |
| 2 | Volta（$VOLTA_HOME/bin/node） |
| 3 | asdf（installs/nodejs最新版本目录） |
| 4 | fnm（node-versions最新版本目录） |
| 5 | NVM（先alias/default，再最新版本） |
| 6 | 常见路径（/opt/homebrew/bin/node、/usr/local/bin/node、/usr/bin/node） |
| 7 | command -v node |
| 8 | 遍历PATH |
找到 Node 后，脚本把它所在 bin 目录注入PATH，然后exec "${NODE_EXEC}" "${NODE_SCRIPT}"启动index.js。所有探测过程都写进包装日志，并内置日志轮转（LOG_RETENTION_COUNT=5，只留最近 5 份）。
Node 版本锁定与 allowed_origins 安全边界
两个设计值得单独强调：
- 版本锁定：
register命令执行前会先调writeNodePathFile()，把安装时刻的 Node 绝对路径写进node_path.txt。这就是为什么升级 Node 管理工具后偶尔要重新register一次——它只是刷新这份锁定文件。 - 安全边界：
allowed_origins只放了扩展 IDhbdgbgagpkpjffpklnamcljpakneikee一个来源。本机其他任何扩展/网页都无法连这个主机，这是整条 stdio 通道的信任锚点。
一键体检：doctor 诊断项与 report 报告导出
这一节给你"出问题先跑什么"的标准动作：mcp-chrome-bridge doctor。
doctor 诊断项一览
doctor命令（实现见 src/scripts/doctor.ts）按 ID 输出逐项状态（OK / WARN / ERROR）与修复建议：
| 检查 ID | 检查什么 |
|---|---|
installation | 包名、版本、平台架构、Node 版本 |
host.files | run_host.sh/bat、index.js、mcp/stdio-config.json三个关键文件是否存在 |
host.permissions | Unix 下run_host.sh是否可执行（Windows 标记 N/A） |
node | 按 run_host 同一套搜索顺序预演会选中哪个 Node，并跑node -v校验主版本 >= 20 |
manifest.<browser> | 逐浏览器检查清单：存在、JSON 可解析、name/type/path/allowed_origins与预期一致，path指向当前安装的包装脚本 |
registry.<browser> | Windows 下注册表项是否存在、值指向的清单文件是否真实存在 |
port.config/port.constant | stdio-config.json的 URL 端口是否为12306，并与NATIVE_SERVER_PORT常量比对 |
connectivity | 向http://<host>:<port>/ping发 GET，验证本地服务是否在线（未启动时提示先点扩展里的 Connect 再重试） |
logs | 日志目录是否已创建 |
常用参数：
--json：输出结构化报告，供脚本消费--fix：先自动修复再体检（见下）-b chrome|chromium|all：指定目标浏览器
因为doctor的 Node 解析逻辑与 run_host完全镜像，跑一次它就知道 Chrome 实际会选中哪个 Node、什么版本——比事后翻日志快得多。
--fix 自动修复的四个动作
mcp-chrome-bridge doctor --fix按顺序尝试并逐项报告成功与否：
- 创建日志目录；
- 重写
node_path.txt（锁定当前 Node）； - 修复
index.js/run_host/cli.js执行权限； - 重新执行用户级注册。
report：把现场打包给 issue
问题复现不了、需要报 issue 时，用report导出脱敏诊断报告（src/scripts/report.ts）：
mcp-chrome-bridge report # Markdown 到 stdout（默认附带包装日志尾部 200 行） mcp-chrome-bridge report --json --output diag.json mcp-chrome-bridge report --include-logs full # 附带完整日志 mcp-chrome-bridge report --copy # 复制剪贴板默认会对用户名、路径、token 做脱敏（--no-redact可关闭），提交前建议先跑这条命令。
排错速查：权限、路径、注册表、Node 版本对照清单
这一节把常见故障压成一张对照表，按报错特征对号入座。
| 症状 | 大概率原因 | 动作 |
|---|---|---|
Native host has exited/Permission denied（macOS/Linux） | run_host.sh缺执行权限（pnpm 安装尤其常见，npm 一般会保留权限位） | mcp-chrome-bridge fix-permissions，或doctor --fix；手动方案：chmod +x <包目录>/run_host.sh（npm list -g mcp-chrome-bridge定位路径） |
| 用户级注册失败 | 用户目录写入受限 | 换系统级：sudo mcp-chrome-bridge register --system |
Node.js executable not found（包装日志） | run_host 十级搜索全部落空 | 设环境变量CHROME_MCP_NODE_PATH指向 Node 绝对路径，或doctor --fix重写node_path.txt |
NODE_MODULE_VERSION不匹配 / 原生模块崩溃 | Chrome 用了与安装时不同版本的 Node | 重新register（刷新node_path.txt），确保node -v>= 20 |
| Node 版本低于 20 | engines.node要求 >= 20.0.0 | 升级 Node 后重装：npm install -g mcp-chrome-bridge |
| Windows "Access denied" / 文件只读 | 文件被标记只读 | mcp-chrome-bridge fix-permissions（会移除只读属性并验证可读性）；或文件资源管理器里检查run_host.bat属性 |
| Windows 扩展找不到主机 | 注册表项缺失或指向已不存在的清单 | reg query "HKCU\Software\Google\Chrome\NativeMessagingHosts\com.chromemcp.nativehost" /ve核对值；重新mcp-chrome-bridge register |
| 清单存在但字段不对 | 手动改过、或装过多个版本 | 核对name/type/path/allowed_origins，重新register --force |
| 端口/连通性异常 | stdio-config.json端口不是 12306，或服务未启动 | mcp-chrome-bridge update-port 12306；在扩展里点 Connect 后重跑doctor |
排查到这一步还没好，最后两个动作：
- 看包装日志：每次 Chrome 拉起主机都会生成一份，含完整 Node 探测轨迹。
- macOS：
~/Library/Logs/mcp-chrome-bridge/native_host_wrapper_unix_<时间戳>.log - Linux：
${XDG_STATE_HOME:-~/.local/state}/mcp-chrome-bridge/logs/ - Windows：
%LOCALAPPDATA%\mcp-chrome-bridge\logs\native_host_wrapper_windows_<时间戳>.log
- macOS：
- 导报告报 issue：
mcp-chrome-bridge report --include-logs tail，附上 OS、Node 版本与安装命令。
接下来还能做什么
装通之后，这条 stdio 通道只是起点：扩展点 Connect 之后，本地服务（端口12306）会把浏览器能力暴露给 MCP 客户端。建议顺着这三处源码继续往下看：
- 本地主机与消息循环的实现：src/native-messaging-host.ts
- MCP 服务端与工具注册：src/mcp/
- 完整管理命令（
register/doctor/report/update-port/fix-permissions）的选项细节：src/cli.ts，安装与注册手册见 app/native-server/install.md
跑通安装只是第一步，把浏览器的自动化能力真正接进你的 AI 工作流，才是这套组合的目标。
【免费下载链接】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），仅供参考
