Chrome 扩展连不上本地程序mcp-chrome-bridge 三步装好并注册 Native Messaging 主机【免费下载链接】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结果提示找不到本地主机或者连接一闪就断。问题多半出在本地的 Native Messaging 主机没装好、没注册好。解法就一个 npm 包mcp-chrome-bridge。装它、注册给 Chrome、验证 stdio 通道——按「装 → 注 → 验」三步走出岔子时再走排障分支。先把链路跑通Connect 在等什么你在扩展里点 Connect背后是一条固定链路扩展点 Connect →chrome.runtime.connectNative→ Chrome 按主机名找 manifest → 拉起 manifest 里path指向的程序 → 通过 stdio 交换 JSON 消息Chrome 不认识任何「约定俗成」的程序它只认清单文件。mcp-chrome-bridge注册时写入的manifest.json长这样字段值作用namecom.chromemcp.nativehostChrome 按这个主机名找清单descriptionNode.js Host for Browser Bridge Extension主机描述pathrun_host.sh绝对路径Windows 是run_host.batChrome 实际拉起的入口typestdioNative Messaging 固定通信方式allowed_originschrome-extension://hbdgbgagpkpjffpklnamcljpakneikee/白名单只放行这一个扩展注意两点。第一allowed_origins是安全边界只有 ID 为hbdgbgagpkpjffpklnamcljpakneikee的扩展能连这个主机其他扩展一律被拒。第二path指向的是包装脚本而不是 Node 脚本。原因看依赖mcp-chrome-bridge里有better-sqlite3这个原生模块对 Node ABI 版本敏感其余还有modelcontextprotocol/sdk、fastify等负责 MCP 与本地服务。如果 Chrome 用 PATH 里随便哪个 Node 拉起它版本和安装时对不上原生模块会直接崩。所以包内置了run_host.sh/run_host.bat先把 Node 可执行文件锁定好再启动index.js。第一步全局安装⌨️ 先确认 Node 版本node -v成功的样子v20.x或更高。package.json的engines要求 Node 20.0.0低于 20 后面 doctor 体检会直接报 ERROR。⌨️ 然后安装npm install -g mcp-chrome-bridgepostinstall钩子会自动跑一遍先给index.js、run_host.shWindows 是run_host.bat、cli.js设 755 执行权限再把当前 Node 路径记进node_path.txt最后尝试用户级注册。postinstall.ts 里有三种分支安装上下文行为普通用户 全局安装自动做用户级注册结尾打印各浏览器结果汇总局部安装没带-g跳过自动注册打印手动注册指引以 root/管理员运行跳过自动注册避免清单写进 root 的家目录提示安装后以普通用户重跑register成功的样子输出末尾出现✓ Manifest written to …和注册汇总✓ Chrome: Success。如果你看到的是手动注册指引继续下一步。第二步注册进 Chrome用户级注册怎么做自动注册没跑成时手动执行⌨️mcp-chrome-bridge register成功的样子每个浏览器一行✓ Manifest written to …最后绿色Native Messaging host registered successfully!。注册做了三件事重写node_path.txt锁定安装时的 Node 版本探测本机装了哪些浏览器Windows 查注册表、macOS 查/Applications/、Linux 用which探测不到就 Chrome 与 Chromium 都注册把清单写进用户级路径Windows 额外建 HKCU 注册表项并回读校验。清单落点如下文件名统一叫com.chromemcp.nativehost.json平台用户级系统级Windows%APPDATA%\Google\Chrome\NativeMessagingHosts\%ProgramFiles%\Google\Chrome\NativeMessagingHosts\macOS~/Library/Application Support/Google/Chrome/NativeMessagingHosts//Library/Google/Chrome/NativeMessagingHosts/Linux~/.config/google-chrome/NativeMessagingHosts//etc/opt/chrome/native-messaging-hosts/Chromium 对应换到~/.config/chromium/…、/etc/chromium/native-messaging-hosts/、~/Library/Application Support/Chromium/…Windows 的注册表键则落在HKCU\Software\Google\Chrome\NativeMessagingHosts\com.chromemcp.nativehost用户级或HKLM\Software\Google\Chrome\NativeMessagingHosts\com.chromemcp.nativehost系统级Chromium 是HKCU\Software\Chromium\…/HKLM\Software\Chromium\…完整定义见 browser-config.ts。只想控制目标浏览器时可以显式传-b chrome|chromium|all或--detect。系统级注册要 sudo 吗大多数情况用户级就够了。只有用户目录写不进去比如公司统管的环境才考虑系统级而且「先试 A 不行再 B」A 是上面这条registerB 才是——sudo mcp-chrome-bridge register --systemWindows 没有 sudo改成「以管理员身份打开命令提示符」后直接跑mcp-chrome-bridge register --system。⚠️ 两个坑CLI 会检测当前提权状态你已经是 root/管理员时不带--system也会走系统级分支系统级注册先把清单写进系统临时目录再复制到系统路径非 Windows 平台顺手chmod 644Windows 上则写 HKLM 注册表项。成功的样子是System-level Native Messaging host registered successfully!。第三步验证连接doctor 一键体检验证分三层看清单。打开上表里的用户级路径确认name/type/path/allowed_origins与表格一致且path指向的脚本真实存在。看扩展。确认扩展已装、带nativeMessaging权限点 Connect。跑体检。⌨️mcp-chrome-bridge doctor它逐项输出 OK / WARN / ERROR 并附修复建议实现见 doctor.ts检查项查什么installation包版本、平台架构、Node 版本host.filesrun_host.sh/run_host.bat、index.js、mcp/stdio-config.json是否存在host.permissionsUnix 下run_host.sh是否有执行位node按与 run_host 相同的优先级链解析 Node校验主版本 20manifest.browser清单存在、JSON 可解析、四个字段符合预期registry.browserWindows 注册表项存在且指向真实清单port.config/port.constantstdio-config.json端口为预期的 12306且与NATIVE_SERVER_PORT常量一致connectivityGET http://127.0.0.1:12306/ping是否通logs日志目录是否已建成功的样子summary 里 error 为 0connectivity显示 200。有 error 时照 nextSteps 走或者一把梭mcp-chrome-bridge doctor --fix会依次创建日志目录、重写node_path.txt、修复执行权限、重新用户级注册并逐项汇报结果--json输出结构化报告-b可指定只看某个浏览器。出问题时三类常见报错的自修顺序Permission denied / Native host has exited多半是执行位丢了pnpm 全局安装尤其容易丢。先试内置修复⌨️mcp-chrome-bridge fix-permissions它给index.js、run_host.sh、cli.js设 755Windows 上则检查并移除只读属性、验证可读性。成功的样子是✓ Execution permissions fixed successfully!。还不行就mcp-chrome-bridge doctor --fix最后再考虑register --system兜底。找不到清单 / Native host not found说明注册没落盘。重跑一次mcp-chrome-bridge register再对照上表核对文件是否真的在那个目录Windows 可以reg query HKCU\Software\Google\Chrome\NativeMessagingHosts\com.chromemcp.nativehost /ve回读注册表值确认指向的清单路径存在。主机起来了但立刻退出看包装日志run_host每次被 Chrome 拉起都会留一份日志目录随平台走平台日志目录日志文件macOS~/Library/Logs/mcp-chrome-bridgenative_host_wrapper_unix_时间戳.logLinux${XDG_STATE_HOME:-~/.local/state}/mcp-chrome-bridge/logsnative_host_wrapper_unix_时间戳.logWindows%LOCALAPPDATA%\mcp-chrome-bridge\logsnative_host_wrapper_windows_时间戳.log日志里记着初始 PATH、逐个尝试的 Node 候选、最终选中的 Node 及其版本、将要exec的命令。目录不可写时会回退到包目录下的logs且只保留最近 5 份。⚠️ 前面说过包装脚本负责锁 Node这里补上它怎么选那串优先级像一把备用钥匙从最可靠的那把试起——CHROME_MCP_NODE_PATH环境变量 →node_path.txt安装时写入→ 相对路径回退dist上溯三级的bin/node→ Volta → asdf → fnm → nvm先 default 别名再最新版→ 常见路径/opt/homebrew/bin/node、/usr/local/bin/node、/usr/bin/node→command -v node→ 遍历整个 PATH。完整实现见 run_host.shWindows 的run_host.bat逻辑相同。多版本 Node 环境下doctor 的node检查走的正是同一条链所以「Chrome 实际会选中哪个 Node」可以先在 doctor 里预演想强制指定就设CHROME_MCP_NODE_PATH那是钥匙串里的第一把。清单生成与注册的核心实现在 utils.ts问题定位完想提 issue先跑mcp-chrome-bridge report导出一份脱敏诊断报告Markdown 或 JSON--include-logs tail可附包装日志尾部。装好之后本地服务与扩展的通信逻辑可以继续看app/native-server/src/native-messaging-host.ts。【免费下载链接】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），仅供参考