★ FEATURED ARTICLE 三大平台装好 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-bridgeChrome MCP Server 的本地 Native Messaging 主机Node.js 实现负责在扩展和本机服务之间做 stdio 双向通信装完得到什么全局可用的三个命令mcp-chrome-bridge注册/诊断管理入口、chrome-mcp-bridge同入口别名、mcp-chrome-stdioMCP stdio 服务端关键产物 1清单文件com.chromemcp.nativehost.json告诉浏览器去哪里、用什么命令拉起主机关键产物 2启动脚本run_host.shmacOS/Linux或run_host.batWindows负责锁定 Node 版本并启动index.js关键产物 3注册表项仅 WindowsHKCU\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.shWindows 为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.jsonmacOS~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.chromemcp.nativehost.jsonLinux~/.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 0Windows 用is-admin。只要已提权即使不带--system也会走系统级分支——所以管理员终端里直接 register和带--system结果一样。用户级注册失败时CLI 会明确打印上面两种补救命令。场景三多浏览器注册Chrome Chromium默认只针对 Chrome。注册命令支持--browser与--detect两个参数来显式控制目标src/scripts/browser-config.tsmcp-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\ChromiummacOS 检查/Applications/下是否有对应.appLinux 用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 的常量一一对应字段值作用namecom.chromemcp.nativehostChrome 靠它定位清单descriptionNode.js Host for Browser Bridge Extension主机描述pathrun_host.shWindows 为run_host.bat的绝对路径浏览器实际拉起的入口typestdio固定为 stdio 通信allowed_origins[chrome-extension://hbdgbgagpkpjffpklnamcljpakneikee/]白名单只有这个扩展 ID 能连上主机清单 JSON 以 2 空格缩进写入JSON.stringify(manifest, null, 2)。核对安装时重点看这四个name/type/path/allowed_originspath必须真实存在且指向当前安装目录下的包装脚本。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显式覆盖最高优先1node_path.txt注册时写入的 Node 绝对路径1.5相对路径回退dist 上溯三级bin/node2Volta$VOLTA_HOME/bin/node3asdfinstalls/nodejs最新版本目录4fnmnode-versions最新版本目录5NVM先alias/default再最新版本6常见路径/opt/homebrew/bin/node、/usr/local/bin/node、/usr/bin/node7command -v node8遍历PATH找到 Node 后脚本把它所在 bin 目录注入PATH然后exec ${NODE_EXEC} ${NODE_SCRIPT}启动index.js。所有探测过程都写进包装日志并内置日志轮转LOG_RETENTION_COUNT5只留最近 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.filesrun_host.sh/bat、index.js、mcp/stdio-config.json三个关键文件是否存在host.permissionsUnix 下run_host.sh是否可执行Windows 标记 N/Anode按 run_host 同一套搜索顺序预演会选中哪个 Node并跑node -v校验主版本 20manifest.browser逐浏览器检查清单存在、JSON 可解析、name/type/path/allowed_origins与预期一致path指向当前安装的包装脚本registry.browserWindows 下注册表项是否存在、值指向的清单文件是否真实存在port.config/port.constantstdio-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.tsmcp-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 deniedmacOS/Linuxrun_host.sh缺执行权限pnpm 安装尤其常见npm 一般会保留权限位mcp-chrome-bridge fix-permissions或doctor --fix手动方案chmod x 包目录/run_host.shnpm list -g mcp-chrome-bridge定位路径用户级注册失败用户目录写入受限换系统级sudo mcp-chrome-bridge register --systemNode.js executable not found包装日志run_host 十级搜索全部落空设环境变量CHROME_MCP_NODE_PATH指向 Node 绝对路径或doctor --fix重写node_path.txtNODE_MODULE_VERSION不匹配 / 原生模块崩溃Chrome 用了与安装时不同版本的 Node重新register刷新node_path.txt确保node -v 20Node 版本低于 20engines.node要求 20.0.0升级 Node 后重装npm install -g mcp-chrome-bridgeWindows 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_时间戳.logLinux${XDG_STATE_HOME:-~/.local/state}/mcp-chrome-bridge/logs/Windows%LOCALAPPDATA%\mcp-chrome-bridge\logs\native_host_wrapper_windows_时间戳.log导报告报 issuemcp-chrome-bridge report --include-logs tail附上 OS、Node 版本与安装命令。接下来还能做什么装通之后这条 stdio 通道只是起点扩展点 Connect 之后本地服务端口12306会把浏览器能力暴露给 MCP 客户端。建议顺着这三处源码继续往下看本地主机与消息循环的实现src/native-messaging-host.tsMCP 服务端与工具注册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），仅供参考
阅读完成 · 觉得有帮助？
