hangwin--mcp-chrome/docs/TROUBLESHOOTING_zh.md at main

wehub/hangwin--mcp-chrome

Fork 0

Files

T

wehub-resource-sync a12bd2c017 chore: import upstream snapshot with attribution

2026-07-13 13:39:08 +08:00

3.5 KiB

Raw Permalink Blame History

🚀 安装和连接问题

快速诊断

运行诊断工具来识别常见问题：

mcp-chrome-bridge doctor

自动修复常见问题：

mcp-chrome-bridge doctor --fix

导出诊断报告

如果需要提交 Issue，可以导出诊断报告：

# 打印 Markdown 报告到终端（复制粘贴到 GitHub Issue）
mcp-chrome-bridge report

# 写入到文件
mcp-chrome-bridge report --output mcp-report.md

# 直接复制到剪贴板
mcp-chrome-bridge report --copy

默认情况下，用户名、路径和令牌会被脱敏。如果你需要提供完整路径，可以使用 --no-redact。

常见问题

连接成功，但是服务启动失败

启动失败基本上都是权限问题或者用包管理工具安装的node导致的启动脚本找不到对应的node。

推荐先运行诊断工具：

mcp-chrome-bridge doctor

核心排查流程

npm包全局安装后，确认清单文件com.chromemcp.nativehost.json的位置，里面有一个path字段，指向的是一个启动脚本:

1.1 检查mcp-chrome-bridge是否安装成功，确保是全局安装的

mcp-chrome-bridge -V

1.2 检查清单文件是否已放在正确目录

windows路径：C:\Users\xxx\AppData\Roaming\Google\Chrome\NativeMessagingHosts

mac路径： /Users/xxx/Library/Application\ Support/Google/Chrome/NativeMessagingHosts

如果npm包安装正常的话，这个目录下会生成一个com.chromemcp.nativehost.json

{
  "name": "com.chromemcp.nativehost",
  "description": "Node.js Host for Browser Bridge Extension",
  "path": "/Users/xxx/Library/pnpm/global/5/.pnpm/mcp-chrome-bridge@1.0.23/node_modules/mcp-chrome-bridge/dist/run_host.sh",
  "type": "stdio",
  "allowed_origins": ["chrome-extension://hbdgbgagpkpjffpklnamcljpakneikee/"]
}

如果发现没有此清单文件，可以尝试命令行执行：mcp-chrome-bridge register

检查日志

日志现在存储在用户可写目录：

macOS: ~/Library/Logs/mcp-chrome-bridge/
Windows: %LOCALAPPDATA%\mcp-chrome-bridge\logs\（例如 C:\Users\xxx\AppData\Local\mcp-chrome-bridge\logs\）
Linux: ~/.local/state/mcp-chrome-bridge/logs/

一般失败的原因就是两种

3.1. run_host.sh(windows是run_host.bat)没有执行权限：运行以下命令修复：

mcp-chrome-bridge fix-permissions

3.2. 脚本找不到node：如果你使用 Node 版本管理工具（nvm、volta、asdf、fnm），可以设置 CHROME_MCP_NODE_PATH 环境变量：

export CHROME_MCP_NODE_PATH=/path/to/your/node

或者运行 mcp-chrome-bridge doctor --fix 来写入当前 Node 路径。

3.3 如果排除了以上两种原因都不行，则查看日志目录的日志，然后提issue

日志位置

包装器日志现在存储在用户可写的位置：

macOS: ~/Library/Logs/mcp-chrome-bridge/
Windows: %LOCALAPPDATA%\mcp-chrome-bridge\logs\
Linux: ~/.local/state/mcp-chrome-bridge/logs/

工具执行超时

有可能长时间连接的时候session会超时，这个时候重新连接即可

效果问题

不同的agent，不同的模型使用工具的效果是不一样的，这些都需要你自行尝试，我更推荐用聪明的agent，比如augment，claude code等等...

3.5 KiB Raw Permalink Blame History Unescape Escape