Chrome MCP 扩展连接失败时：排查并修复…

当 macOS 上 Claude in Chrome MCP 工具报 “Browser extension is not connected” 或浏览器自动化不稳定时，用于诊断原生主机、socket 与 Chrome 原生消息配置冲突。

适用场景

解决思路

1. 当 mcp__claude-in-chrome__* 工具失败、报 “Browser extension is not connected”、浏览器自动化不稳定/超时、更新 Claude Code 或 Claude.app 后、在 Claude Code CLI 与 Claude.app (Cowork) 之间切换、或 native host 进程在运行但 MCP 工具仍失败时，使用此排查流程。
2. 先处理主因：Claude.app (Cowork) 与 Claude Code CLI 使用不同的 native messaging host 和 socket 格式，二者会冲突；判断你实际使用哪一个做浏览器自动化，然后禁用另一个。
3. 如果使用 Claude Code CLI 做浏览器自动化（不是 Cowork）：执行 mv ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_browser_extension.json ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_browser_extension.json.disabled，禁用 Claude.app 的 native messaging 配置。
4. 如果使用 Claude Code CLI：执行 cat ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json，确保 Claude Code 配置存在并指向 wrapper。
5. 如果使用 Cowork (Claude.app) 做浏览器自动化：执行 mv ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json.disabled，禁用 Claude Code 的 native messaging 配置。
6. 不要同时启用两个 native host；只能选择 Claude Code CLI 或 Claude.app (Cowork) 之一，并禁用另一个。
7. 可用切换脚本：把 chrome-mcp-toggle 函数加入 ~/.zshrc 或直接运行；函数内设置 CONFIG_DIR=~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts、CLAUDE_APP=$CONFIG_DIR/com.anthropic.claude_browser_extension.json、CLAUDE_CODE=$CONFIG_DIR/com.anthropic.claude_code_browser_extension.json。
8. chrome-mcp-toggle 逻辑：若 CLAUDE_APP 存在且 .disabled 不存在，则把 CLAUDE_APP 改名为 .disabled，并在 CLAUDE_CODE.disabled 存在时改回 CLAUDE_CODE，然后提示 Switched to Claude Code CLI，需重启 Chrome 和 Claude Code。
9. chrome-mcp-toggle 逻辑：若 CLAUDE_CODE 存在且 .disabled 不存在，则把 CLAUDE_CODE 改名为 .disabled，并在 CLAUDE_APP.disabled 存在时改回 CLAUDE_APP，然后提示 Switched to Claude.app (Cowork)，需重启 Chrome。
10. chrome-mcp-toggle 状态不明确时，执行 ls -la "$CONFIG_DIR"/com.anthropic*.json* 检查配置。使用后运行 chrome-mcp-toggle，然后重启 Chrome（若切到 CLI 也重启 Claude Code）。
11. 快速诊断第 1 步：执行 ps aux | grep chrome-native-host | grep -v grep，判断正在运行哪个 native host binary；Claude.app 显示 /Applications/Claude.app/Contents/Helpers/chrome-native-host，Claude Code 显示 ~/.local/share/claude/versions/X.X.X --chrome-native-host。
12. 快速诊断第 2 步：检查 socket 位置；Claude Code 执行 ls -la "$(getconf DARWIN_USER_TEMP_DIR)/claude-mcp-browser-bridge-$USER"，Claude.app 执行 ls -la /tmp/claude-mcp-browser-bridge-$USER/。
13. 快速诊断第 3 步：执行 lsof -U 2>&1 | grep claude-mcp-browser-bridge，查看 native host 连接到什么。
14. 快速诊断第 4 步：执行 ls ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic*.json，查看哪些配置处于激活状态。
15. 关键认知：MCP 在启动时连接；如果 Claude Code 启动时 browser bridge 未就绪，整个会话连接都会失败。修复通常是：确保 Chrome + extension 以正确配置运行，然后重启 Claude Code。
16. 完整重置（Claude Code CLI）第 1 步：确保正确配置激活，执行 mv ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_browser_extension.json ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_browser_extension.json.disabled 2>/dev/null。
17. 完整重置第 2 步：更新 wrapper 使用最新 Claude Code 版本；执行 cat > ~/.claude/chrome/chrome-native-host << 'EOF' #!/bin/bash LATEST=$(ls -t ~/.local/share/claude/versions/ 2>/dev/null | head -1) exec "$HOME/.local/share/claude/versions/$LATEST" --chrome-native-host EOF chmod +x ~/.claude/chrome/chrome-native-host。
18. 完整重置第 3 步：杀掉现有 native host 并清理 socket；执行 pkill -f chrome-native-host、rm -rf /tmp/claude-mcp-browser-bridge-$USER/、rm -f "$(getconf DARWIN_USER_TEMP_DIR)/claude-mcp-browser-bridge-$USER"。
19. 完整重置第 4 步：重启 Chrome；执行 osascript -e 'quit app "Google Chrome"' && sleep 2 && open -a "Google Chrome"。
20. 完整重置第 5 步：等待 Chrome 启动后，点击 Claude extension 图标。
21. 完整重置第 6 步：验证正确 native host 正在运行；执行 ps aux | grep chrome-native-host | grep -v grep，应显示 ~/.local/share/claude/versions/X.X.X --chrome-native-host。
22. 完整重置第 7 步：验证 socket 存在；执行 ls -la "$(getconf DARWIN_USER_TEMP_DIR)/claude-mcp-browser-bridge-$USER"。
23. 完整重置第 8 步：重启 Claude Code。
24. 处理多个 Chrome Profiles：如果多个 Chrome profile 都安装了 Claude extension，每个都会生成自己的 native host 和 socket，造成混乱；修复是只在 ONE 个 Chrome profile 中启用 Claude extension。
25. 处理多个 Claude Code Sessions：运行多个 Claude Code 实例会造成 socket 冲突；修复是一次只运行一个 Claude Code session，或关闭其他会话后用 /mcp 重连。
26. 处理 wrapper 硬编码版本：检查 cat ~/.claude/chrome/chrome-native-host；若出现 exec "/Users/.../.local/share/claude/versions/2.0.76" --chrome-native-host 这类硬编码版本，则更新后可能过期；应使用 $(ls -t ...) 查找最新版本，并按完整重置中的动态版本 wrapper 替换。
27. 处理 TMPDIR 未设置：执行 echo $TMPDIR，应显示 /var/folders/XX/.../T/；若未设置，在 ~/.zshrc 添加 export TMPDIR="${TMPDIR:-$(getconf DARWIN_USER_TEMP_DIR)}"。
28. 执行诊断深挖脚本，依次输出并检查：Native Host Binary（ps aux | grep chrome-native-host | grep -v grep）、Claude Code socket（ls -la "$(getconf DARWIN_USER_TEMP_DIR)/claude-mcp-browser-bridge-$USER" 2>&1）、Claude.app socket（ls -la /tmp/claude-mcp-browser-bridge-$USER/ 2>&1）、Native Host Open Files（pgrep -f chrome-native-host | xargs -I {} lsof -p {} 2>/dev/null | grep -E "(sock|claude-mcp)"）、Active Native Messaging Configs（ls ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic*.json 2>/dev/null）、Custom Wrapper Contents（cat ~/.claude/chrome/chrome-native-host 2>/dev/null || echo "No custom wrapper"）、TMPDIR（echo "TMPDIR=$TMPDIR" 和 echo "Expected: $(getconf DARWIN_USER_TEMP_DIR)"）。
29. 按文件参考定位问题：~/.claude/chrome/chrome-native-host 是 Claude Code 自定义 wrapper；/Applications/Claude.app/Contents/Helpers/chrome-native-host 是 Claude.app (Cowork) native host；~/.local/share/claude/versions/<version> 是 Claude Code binary（以 --chrome-native-host 运行）；~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_browser_extension.json 是 Claude.app native host 配置；~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json 是 Claude Code native host 配置；$TMPDIR/claude-mcp-browser-bridge-$USER 是 Claude Code socket 文件；/tmp/claude-mcp-browser-bridge-$USER/<PID>.sock 是 Claude.app socket 文件。
30. 最终检查原则：主要问题是 Claude.app (Cowork) 与 Claude Code 使用不兼容 socket 格式的不同 native hosts；修复是禁用你未使用的那一个 native messaging 配置；任何修复后必须重启 Chrome 和 Claude Code；只在 one 个 Chrome profile 中保留 Claude extension；只运行一个 Claude Code 实例。

适用边界 · 注意事项

• Linux 或 Windows 用户不适用：本技能覆盖 macOS 专属路径和工具（~/Library/Application Support/、osascript）。
• 与 Claude extension 无关的一般 Chrome 自动化问题、Claude.app 桌面端问题（非浏览器相关）、网络连接问题、Chrome 扩展安装问题（应使用 Chrome Web Store 支持）不适用。