企业官网建设流程全解析

mcp-chrome 连接故障排查指南：MCP 服务起不来，用 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

mcp-chrome（Chrome MCP Server）通过"浏览器扩展 + 本地 Node.js 桥接进程"把 Chrome 能力暴露给 Claude 等 AI 助手。它的最高频故障是：扩展面板显示已连接，MCP 服务却始终起不来——本质是扩展与本地桥接之间的某一环断了。最短解决路径只有三步：跑mcp-chrome-bridge doctor定位 →mcp-chrome-bridge doctor --fix自动修复 → 仍不行就mcp-chrome-bridge report导出脱敏诊断报告提 Issue。

先看懂链路：故障到底发生在哪里

mcp-chrome 的工作链路分三段：Chrome 扩展通过 Native Messaging 协议按清单文件（manifest）找到启动脚本（run_host.sh/run_host.bat）；脚本自行寻找Node 运行时，拉起本地桥接进程；桥接进程在http://127.0.0.1:12306/mcp提供 MCP 服务（端口见 stdio-config.json）。四样部件——清单文件、启动脚本、Node、端口配置——任何一环出错，都会表现成"连上了但服务没起来"。理解这条链路，下面的排障就能对号入座。

一步自检：先跑 doctor，别急着翻日志

遇到连接异常，第一条命令永远是：

mcp-chrome-bridge doctor

它逐项输出带徽标的结果，末了给出 Next steps 建议列表，退出码 0 表示无致命错误、1 表示存在[ERROR]。三档徽标怎么读：

如果看到任何[ERROR]，直接执行自动修复：

mcp-chrome-bridge doctor --fix

--fix会依次尝试四类修复（实现见 scripts/doctor.ts 的attemptFixes），每项成功与否都单独回报：

⚠️ 自动修复只做安全的用户级操作：写用户可写目录、写用户级注册表，不会碰系统目录，也不做系统级安装。

另外两个实用参数：

• mcp-chrome-bridge doctor --json：输出结构化 JSON（含environment、fixes、checks、nextSteps），方便脚本化处理；
• mcp-chrome-bridge doctor -b chrome|chromium|all：只针对指定浏览器做清单/注册表检查，不指定时自动探测已安装浏览器。

按现象排障

下面每个现象都按"现象 → 判定 → 根因 → 修复 → 验证"五步走，先看现象对号入座，再执行对应步骤。

现象一：扩展显示已连接，但 Chrome 拉不起宿主进程

现象：扩展图标显示连接成功，但工具调用全部失败；wrapper 日志里能看到脚本被调用了，Node 也解析成功，却没有后续进程。

判定：跑mcp-chrome-bridge doctor，看Host permissions检查项。如果看到[ERROR] run_host.sh is not executable，即命中。

根因：全局安装时run_host.sh没带上执行权限（npm 在某些环境下会丢失 mode 位），Chrome 作为非登录用户环境执行脚本时直接被系统拒绝。该检查仅在非 Windows 平台生效（见 scripts/doctor.ts）。

修复：

mcp-chrome-bridge fix-permissions

该命令在 Unix 下对index.js、run_host.sh、cli.js执行chmod 755（实现见 scripts/utils.ts 的ensureExecutionPermissions）。也可以手动chmod +x对应脚本，但用命令更省心，它三个文件一起处理。

验证：重跑mcp-chrome-bridge doctor，Host permissions变为[OK]；再到扩展里点击 Connect，工具调用恢复正常。

现象二：启动脚本报 "Node.js executable not found"

现象：wrapper 日志（见"日志位置"一节）末尾出现ERROR: Node.js executable not found!，列出它搜索过的全部来源；或 doctor 中Node executable项报[ERROR] Node.js executable not found by wrapper search order。

判定：用node -v确认终端里 Node 能正常执行；如果终端正常、脚本却找不到，再看 doctor 输出。如果你用 nvm、volta、asdf、fnm 等版本管理工具，基本就是它——Chrome 拉起脚本时的 PATH 与你的终端不一致，node不在脚本可见的搜索范围内。

根因：run_host 脚本运行在 Chrome 的最小化环境里，必须自己找 Node（scripts/run_host.sh）；版本管理工具装出的 Node 往往只存在于 shell 注入的 PATH 中，脚本的默认搜索链摸不到。

修复（二选一）：

# 方案 A：显式指定 Node 路径，优先级最高 export CHROME_MCP_NODE_PATH=/path/to/your/node

# 方案 B：让 doctor 把当前 Node 路径写入 node_path.txt mcp-chrome-bridge doctor --fix

💡 方案 B 更推荐：它记录的是安装期所用的 Node，能保证与 better-sqlite3 等原生模块的编译版本一致，避免 NODE_MODULE_VERSION 不匹配（设计意图见 scripts/utils.ts 的writeNodePathFile注释）。另外 doctor 若报Node.js ... is too old (requires >= 20.0.0)，说明找到的 Node 主版本低于 20（engines.node要求），需要升级 Node 而不是改路径。

验证：wrapper 日志中出现Found node via node_path.txt或Found node via CHROME_MCP_NODE_PATH，且Node version一行显示v20以上；扩展重新 Connect 后服务正常。

现象三：清单文件缺失，或 path 字段指向错误

现象：扩展根本连不上，或连接立即断开；doctor 中manifest.chrome/manifest.chromium项报[ERROR] Manifest not found，或列出具体字段问题（如path does not match installed wrapper、allowed_origins missing chrome-extension://hbdgbgagpkpjffpklnamcljpakneikee/）。

判定：先确认包已全局安装：

mcp-chrome-bridge -V

应输出版本号（当前为1.0.29）。package.json还注册了别名chrome-mcp-bridge，指向同一份dist/cli.js，可以互换验证。再检查用户级清单文件是否落在正确目录（各平台路径定义见 scripts/browser-config.ts）：

Chromium 把路径中的Google/Chrome（Windows 为Chromium）替换掉即可。文件正常时内容形如：

{ "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/"] }

如果path指向一个已不存在的目录（比如升级后包路径变了），就是命中本现象。

根因：npm 包安装/升级后清单没有重新生成，或注册流程被中断，导致 Chrome 按清单找不到可用的启动脚本。

修复：

mcp-chrome-bridge register

常用选项：-b chrome|chromium|all指定浏览器，-d显式自动探测，-s系统级安装（需要管理员/sudo，Windows 下同时写 HKLM 注册表，见 cli.ts）。普通用户保持默认的用户级注册即可。

验证：重跑 doctor，manifest.*变[OK]；Windows 上registry.chrome检查项也应[OK]（HKCU 下Software\Google\Chrome\NativeMessagingHosts\com.chromemcp.nativehost的默认值指向真实存在的清单文件）。

现象四：之前一切正常，用着用着会话断了

现象：长时间连接后，工具调用突然全部失败，或 doctor 的Connectivity项显示[WARN] GET http://127.0.0.1:12306/ping failed，而Port config/Port constant都是[OK]。

判定：跑 doctor 区分两种情况：如果port.config也报[ERROR]，说明 stdio-config.json 里的端口被改过，用mcp-chrome-bridge update-port 12306改回来；如果端口检查正常、仅连通性探测失败（doctor 内置 1.5 秒超时探测/ping），则命中本现象。

根因：本地桥接与 MCP 服务的会话有空闲超时机制，长时间无操作后 session 失效（docs/TROUBLESHOOTING_zh.md 明确说明）；此时服务进程未在运行，/ping自然探不通。这不是安装问题，doctor 修不了，也无需修。

修复：在扩展面板重新点击 Connect，或重启宿主进程即可，不需要重装任何组件。

验证：重跑mcp-chrome-bridge doctor，Connectivity项显示[OK] GET http://127.0.0.1:12306/ping -> 200。

知其所以然：Node 解析优先级与日志机制

启动脚本怎么找 Node

run_host 脚本被 Chrome 以最小化环境拉起，它按固定顺序逐级尝试（完整实现见 scripts/run_host.sh，doctor 的node检查复刻了同一套逻辑）：

找到 Node 后，脚本把 Node 所在目录追加进PATH再exec启动index.js，由 native-messaging-host.ts 处理 Native Messaging 协议消息并连接本地 MCP 服务。所以看到"找不到 node"报错时，按优先级从上往下想：先设CHROME_MCP_NODE_PATH，再让doctor --fix写node_path.txt，成本最低。

日志存在哪、怎么命名、怎么轮转

包装器日志统一放在用户可写目录（路径计算见 scripts/utils.ts 的getLogDir），避免写 npm 包目录带来的权限问题：

若用户目录不可写，脚本回退到包内dist/logs（见 run_host.sh 开头）。文件按时间戳命名：macOS/Linux 为native_host_wrapper_unix_<时间戳>.log与native_host_stderr_unix_<时间戳>.log，Windows 对应native_host_wrapper_windows_<时间戳>.log与native_host_stderr_windows_<时间戳>.log。wrapper 日志记录调用时的 PATH、各优先级尝试过程和最终选用的 Node；stderr 日志记录 Node 进程本身的报错。为控制磁盘占用，脚本内置轮转：wrapper 与 stderr 各保留最近 5 份（LOG_RETENTION_COUNT=5），超出自动清理。

提 Issue 的正确姿势：用 report 导出诊断报告

本地排无可排时，别只贴一句"连不上"——先导出诊断报告，它比口头描述有价值得多：

# 打印 Markdown 报告到终端（直接复制粘贴到 Issue） mcp-chrome-bridge report # 写入文件 mcp-chrome-bridge report --output mcp-report.md # 直接复制到剪贴板（macOS 用 pbcopy，Windows 用 clip，Linux 依次尝试 wl-copy/xclip/xsel） mcp-chrome-bridge report --copy

报告由 scripts/report.ts 的runReport组装，默认包含：环境信息（平台、OS、Node 版本与 execPath、CWD）、npm/pnpm 版本、关键环境变量快照（CHROME_MCP_NODE_PATH、VOLTA_HOME、ASDF_DATA_DIR、FNM_DIR、NVM_DIR等）、doctor 诊断 JSON、包装器日志、各浏览器用户级/系统级清单快照，以及 Windows 下的注册表项。

默认脱敏覆盖范围（createRedactor实现）：

日志收集默认tail模式（每文件末尾 256KB 且至多 200 行），可用参数调整：

full模式单文件上限 1MB、最多收集 6 个日志文件，避免报告体积失控。

⚠️ 只有当需要排查"清单path指向了哪个具体目录"这类路径问题、且确认对方是可信维护者时，才显式关闭脱敏：mcp-chrome-bridge report --no-redact。公共 Issue 里永远用默认脱敏输出。

速查表与源码索引

现象 → 根因 → 命令速查表

相关源码与文档索引

• 排障文档主体：docs/TROUBLESHOOTING_zh.md
• CLI 命令定义（doctor / report / register / fix-permissions / update-port）：app/native-server/src/cli.ts
• 诊断检查与自动修复实现：app/native-server/src/scripts/doctor.ts
• 报告导出与脱敏实现：app/native-server/src/scripts/report.ts
• 启动脚本（Unix / Windows）：app/native-server/src/scripts/run_host.sh、app/native-server/src/scripts/run_host.bat
• 清单注册、日志路径、权限修复工具函数：app/native-server/src/scripts/utils.ts
• 浏览器清单路径与 Windows 注册表键配置：app/native-server/src/scripts/browser-config.ts
• 宿主名 / 扩展 ID / 描述常量：app/native-server/src/scripts/constant.ts
• MCP 服务端口配置（12306）：app/native-server/src/mcp/stdio-config.json
• 原生消息宿主进程：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