mcp-chrome 连接故障排查指南：MCP 服务起不来，用 doctor 三步定位修复

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-chromemcp-chromeChrome 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]。三档徽标怎么读徽标含义你要做什么[OK]该检查项正常不用管[WARN]能跑但不稳如 Node 来源可疑、/ping探测失败留意必要时修复[ERROR]致命问题服务必然起不来按该行下方Fix:提示处理如果看到任何[ERROR]直接执行自动修复mcp-chrome-bridge doctor --fix--fix会依次尝试四类修复实现见 scripts/doctor.ts 的attemptFixes每项成功与否都单独回报修复项行为logs递归创建日志目录确保可写node_path把当前process.execPath写入 dist 目录的node_path.txt供启动脚本按第二优先级使用permissions对run_host.sh、index.js、cli.js统一设置可执行权限Windows 下移除只读属性register以用户级权限重新注册 Native Messaging 宿主⚠️ 自动修复只做安全的用户级操作写用户可写目录、写用户级注册表不会碰系统目录也不做系统级安装。另外两个实用参数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 doctorHost 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 的最小化环境里必须自己找 Nodescripts/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 主版本低于 20engines.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平台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.jsonChromium 把路径中的Google/ChromeWindows 为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系统级安装需要管理员/sudoWindows 下同时写 HKLM 注册表见 cli.ts。普通用户保持默认的用户级注册即可。验证重跑 doctormanifest.*变[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 doctorConnectivity项显示[OK] GET http://127.0.0.1:12306/ping - 200。知其所以然Node 解析优先级与日志机制启动脚本怎么找 Noderun_host 脚本被 Chrome 以最小化环境拉起它按固定顺序逐级尝试完整实现见 scripts/run_host.shdoctor 的node检查复刻了同一套逻辑优先级来源说明0CHROME_MCP_NODE_PATH环境变量最高优先支持绝对路径或目录自动补/node或\node.exe、~/展开1node_path.txt安装期 /doctor --fix写入的 Node 路径保证与原生模块编译版本一致1.5相对路径回退Unix../../../bin/nodeWindows..\..\..\node.exe从 dist 目录向上三级2Volta$VOLTA_HOME/bin/node默认~/.volta/bin/node3asdf$ASDF_DATA_DIR/installs/nodejs/最新版本/bin/node4fnm$FNM_DIR/node-versions/最新版本/installation/bin/nodeWindows 无bin层5NVM仅 Unix优先$NVM_DIR/alias/default指向版本其次最新版本6常见路径/opt/homebrew/bin/node、/usr/local/bin/node、/usr/bin/node等7command -v node脚本内建命令查找8遍历PATH逐目录查找可执行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 包目录带来的权限问题平台日志目录macOS~/Library/Logs/mcp-chrome-bridge/Windows%LOCALAPPDATA%\mcp-chrome-bridge\logs\Linux$XDG_STATE_HOME/mcp-chrome-bridge/logs/未设置时回退~/.local/state/mcp-chrome-bridge/logs/若用户目录不可写脚本回退到包内dist/logs见 run_host.sh 开头。文件按时间戳命名macOS/Linux 为native_host_wrapper_unix_时间戳.log与native_host_stderr_unix_时间戳.logWindows 对应native_host_wrapper_windows_时间戳.log与native_host_stderr_windows_时间戳.log。wrapper 日志记录调用时的 PATH、各优先级尝试过程和最终选用的 Nodestderr 日志记录 Node 进程本身的报错。为控制磁盘占用脚本内置轮转wrapper 与 stderr 各保留最近 5 份LOG_RETENTION_COUNT5超出自动清理。提 Issue 的正确姿势用 report 导出诊断报告本地排无可排时别只贴一句连不上——先导出诊断报告它比口头描述有价值得多# 打印 Markdown 报告到终端直接复制粘贴到 Issue mcp-chrome-bridge report # 写入文件 mcp-chrome-bridge report --output mcp-report.md # 直接复制到剪贴板macOS 用 pbcopyWindows 用 clipLinux 依次尝试 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实现类别处理方式主目录os.homedir()、USERPROFILE、HOME及当前用户名整体替换敏感键值含TOKEN/PASSWORD/SECRET/API_KEY/ACCESS_KEY/PRIVATE_KEY关键字的赋值HTTP 头AuthorizationBearer/Basic、Cookie/Set-Cookie、x-api-key/api-key/x-auth-token/x-access-token其他邮箱地址、/Users/user与C:\Users\user路径日志收集默认tail模式每文件末尾 256KB 且至多 200 行可用参数调整参数说明默认值--json输出 JSON 而非 MarkdownMarkdown--include-logs none\|tail\|full日志收集模式tail--log-lines ntail模式下包含的日志行数200-b browser指定浏览器范围自动探测full模式单文件上限 1MB、最多收集 6 个日志文件避免报告体积失控。⚠️ 只有当需要排查清单path指向了哪个具体目录这类路径问题、且确认对方是可信维护者时才显式关闭脱敏mcp-chrome-bridge report --no-redact。公共 Issue 里永远用默认脱敏输出。速查表与源码索引现象 → 根因 → 命令速查表现象最可能根因处理命令扩展已连接宿主进程拉不起来run_host.sh无执行权限mcp-chrome-bridge fix-permissions日志报Node.js executable not found版本管理工具的 Node 不在脚本搜索链export CHROME_MCP_NODE_PATH...或mcp-chrome-bridge doctor --fixdoctor 报Manifest not found/path does not match清单缺失或包路径已变mcp-chrome-bridge registerdoctor 报 Node 版本too oldNode 主版本低于 20升级 Node 到 20 后重跑doctor --fix/ping探测失败但端口正常会话空闲超时扩展中重新点击 Connect端口配置项[ERROR]stdio-config.json 端口被改mcp-chrome-bridge update-port 12306以上都排除不了未知问题mcp-chrome-bridge report导出报告提 Issue相关源码与文档索引排障文档主体docs/TROUBLESHOOTING_zh.mdCLI 命令定义doctor / report / register / fix-permissions / update-portapp/native-server/src/cli.ts诊断检查与自动修复实现app/native-server/src/scripts/doctor.ts报告导出与脱敏实现app/native-server/src/scripts/report.ts启动脚本Unix / Windowsapp/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.tsMCP 服务端口配置12306app/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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考