claude-in-chrome-troubleshooting

Claude in Chrome MCP 故障排除

当 Claude in Chrome MCP 工具无法连接或运行不稳定时，请使用本指南。

适用情况

• mcp__claude-in-chrome__* 工具报错“Browser extension is not connected”
• 浏览器自动化运行不稳定或超时
• 更新 Claude Code 或 Claude.app 后
• 在 Claude Code CLI 和 Claude.app（Cowork）之间切换时
• Native host 进程正在运行，但 MCP 工具仍然失败

不适用情况

• Linux 或 Windows 用户——本指南介绍的是 macOS 专属路径和工具（~/Library/Application Support/、osascript）
• 与 Claude 扩展无关的一般 Chrome 自动化问题
• Claude.app 桌面应用问题（与浏览器无关）
• 网络连接问题
• Chrome 扩展安装问题（请联系 Chrome Web Store 支持）

Claude.app 与 Claude Code 冲突（主要问题）

**背景：**Claude.app 添加 Cowork 支持（从桌面应用进行浏览器自动化）时，引入了一个与 Claude Code CLI 冲突的竞争性 native messaging host。

两个 Native Host，两种 Socket 格式

组件	Native Host 二进制文件	Socket 位置
Claude.app（Cowork）	/Applications/Claude.app/Contents/Helpers/chrome-native-host	/tmp/claude-mcp-browser-bridge-$USER/<PID>.sock
Claude Code CLI	~/.local/share/claude/versions/<version> --chrome-native-host	$TMPDIR/claude-mcp-browser-bridge-$USER（单个文件）

冲突原因

1. 两者都会在 Chrome 中注册 native messaging 配置：

   • com.anthropic.claude_browser_extension.json → Claude.app helper
   • com.anthropic.claude_code_browser_extension.json → Claude Code wrapper

2. Chrome 扩展按名称请求 native host

3. 如果启用了错误的配置，就会运行错误的二进制文件

4. 错误的二进制文件会以 MCP 客户端无法识别的格式或位置创建 socket

5. 结果：即使一切看似正常运行，仍会出现“Browser extension is not connected”

解决方法：禁用 Claude.app 的 Native Host

如果你使用 Claude Code CLI 进行浏览器自动化（而非 Cowork）：

# Disable the Claude.app native messaging config
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

# Ensure the Claude Code config exists and points to the wrapper
cat ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json

如果你使用 Cowork（Claude.app）进行浏览器自动化：

# Disable the Claude Code native messaging config
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

**不能同时使用两者。**请选择其中一个，并禁用另一个。

切换脚本

将以下内容添加到 ~/.zshrc，或直接运行：

chrome-mcp-toggle() {
    local CONFIG_DIR=~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts
    local CLAUDE_APP="$CONFIG_DIR/com.anthropic.claude_browser_extension.json"
    local CLAUDE_CODE="$CONFIG_DIR/com.anthropic.claude_code_browser_extension.json"

    if [[ -f "$CLAUDE_APP" && ! -f "$CLAUDE_APP.disabled" ]]; then
        # Currently using Claude.app, switch to Claude Code
        mv "$CLAUDE_APP" "$CLAUDE_APP.disabled"
        [[ -f "$CLAUDE_CODE.disabled" ]] && mv "$CLAUDE_CODE.disabled" "$CLAUDE_CODE"
        echo "Switched to Claude Code CLI"
        echo "Restart Chrome and Claude Code to apply"
    elif [[ -f "$CLAUDE_CODE" && ! -f "$CLAUDE_CODE.disabled" ]]; then
        # Currently using Claude Code, switch to Claude.app
        mv "$CLAUDE_CODE" "$CLAUDE_CODE.disabled"
        [[ -f "$CLAUDE_APP.disabled" ]] && mv "$CLAUDE_APP.disabled" "$CLAUDE_APP"
        echo "Switched to Claude.app (Cowork)"
        echo "Restart Chrome to apply"
    else
        echo "Current state unclear. Check configs:"
        ls -la "$CONFIG_DIR"/com.anthropic*.json* 2>/dev/null
    fi
}

用法：运行 chrome-mcp-toggle，然后重启 Chrome（如果要切换到 CLI，也要重启 Claude Code）。

快速诊断

# 1. Which native host binary is running?
ps aux | grep chrome-native-host | grep -v grep
# Claude.app: /Applications/Claude.app/Contents/Helpers/chrome-native-host
# Claude Code: ~/.local/share/claude/versions/X.X.X --chrome-native-host

# 2. Where is the socket?
# For Claude Code (single file in TMPDIR):
ls -la "$(getconf DARWIN_USER_TEMP_DIR)/claude-mcp-browser-bridge-$USER" 2>&1

# For Claude.app (directory with PID files):
ls -la /tmp/claude-mcp-browser-bridge-$USER/ 2>&1

# 3. What's the native host connected to?
lsof -U 2>&1 | grep claude-mcp-browser-bridge

# 4. Which configs are active?
ls ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic*.json

关键要点

**MCP 会在启动时建立连接。**如果 Claude Code 启动时浏览器桥接尚未就绪，整个会话期间连接都会失败。通常的解决方法是：确保 Chrome 和扩展已运行且配置正确，然后重启 Claude Code。

完全重置步骤（Claude Code CLI）

# 1. Ensure correct config is active
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

# 2. Update the wrapper to use latest Claude Code version
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

# 3. Kill existing native host and clean sockets
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"

# 4. Restart Chrome
osascript -e 'quit app "Google Chrome"' && sleep 2 && open -a "Google Chrome"

# 5. Wait for Chrome, click Claude extension icon

# 6. Verify correct native host is running
ps aux | grep chrome-native-host | grep -v grep
# Should show: ~/.local/share/claude/versions/X.X.X --chrome-native-host

# 7. Verify socket exists
ls -la "$(getconf DARWIN_USER_TEMP_DIR)/claude-mcp-browser-bridge-$USER"

# 8. Restart Claude Code

其他常见原因

多个 Chrome 配置文件

如果你在多个 Chrome 配置文件中安装了 Claude 扩展，每个配置文件都会启动自己的 native host 和 socket，可能导致混乱。

**解决方法：**仅在一个 Chrome 配置文件中启用 Claude 扩展。

多个 Claude Code 会话

同时运行多个 Claude Code 实例可能导致 socket 冲突。

**解决方法：**每次只运行一个 Claude Code 会话，或关闭其他会话后使用 /mcp 重新连接。

Wrapper 中的硬编码版本

~/.claude/chrome/chrome-native-host 中的 wrapper 可能硬编码了一个版本号，并在更新后过期。

诊断：

cat ~/.claude/chrome/chrome-native-host
# Bad: exec "/Users/.../.local/share/claude/versions/2.0.76" --chrome-native-host
# Good: Uses $(ls -t ...) to find latest

**解决方法：**使用上方“完全重置步骤”中所示的动态版本 wrapper。

未设置 TMPDIR

Claude Code 需要设置 TMPDIR 才能找到 socket。

# Check
echo $TMPDIR
# Should show: /var/folders/XX/.../T/

# Fix: Add to ~/.zshrc
export TMPDIR="${TMPDIR:-$(getconf DARWIN_USER_TEMP_DIR)}"

深入诊断

echo "=== Native Host Binary ==="
ps aux | grep chrome-native-host | grep -v grep

echo -e "\n=== Socket (Claude Code location) ==="
ls -la "$(getconf DARWIN_USER_TEMP_DIR)/claude-mcp-browser-bridge-$USER" 2>&1

echo -e "\n=== Socket (Claude.app location) ==="
ls -la /tmp/claude-mcp-browser-bridge-$USER/ 2>&1

echo -e "\n=== Native Host Open Files ==="
pgrep -f chrome-native-host | xargs -I {} lsof -p {} 2>/dev/null | grep -E "(sock|claude-mcp)"

echo -e "\n=== Active Native Messaging Configs ==="
ls ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic*.json 2>/dev/null

echo -e "\n=== Custom Wrapper Contents ==="
cat ~/.claude/chrome/chrome-native-host 2>/dev/null || echo "No custom wrapper"

echo -e "\n=== TMPDIR ==="
echo "TMPDIR=$TMPDIR"
echo "Expected: $(getconf DARWIN_USER_TEMP_DIR)"

文件参考

文件	用途
~/.claude/chrome/chrome-native-host	Claude Code 的自定义包装脚本
/Applications/Claude.app/Contents/Helpers/chrome-native-host	Claude.app（Cowork）的原生主机
~/.local/share/claude/versions/<version>	Claude Code 二进制文件（使用 --chrome-native-host 运行）
~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_browser_extension.json	Claude.app 原生主机的配置
~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json	Claude Code 原生主机的配置
$TMPDIR/claude-mcp-browser-bridge-$USER	套接字文件（Claude Code）
/tmp/claude-mcp-browser-bridge-$USER/<PID>.sock	套接字文件（Claude.app）

总结

1. 主要问题： Claude.app（Cowork）和 Claude Code 使用不同的原生主机，套接字格式不兼容
2. 修复方法： 禁用你不使用的那一方的原生消息配置
3. 完成任何修复后： 必须重启 Chrome 和 Claude Code（MCP 会在启动时连接）
4. 一个配置文件： 只在一个 Chrome 配置文件中安装 Claude 扩展
5. 一个会话： 只运行一个 Claude Code 实例

---

原始技能由 @ExaAILabs 的 @jeffzwang 创建。已针对当前版本的 Claude Desktop 和 Claude Code 进行增强和更新。