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）之间切换时
• 原生宿主进程正在运行，但 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 冲突的竞争性原生消息宿主。

两个原生宿主，两种套接字格式

组件	原生宿主二进制文件	套接字位置
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 中注册原生消息配置：

   • com.anthropic.claude_browser_extension.json → Claude.app 助手
   • com.anthropic.claude_code_browser_extension.json → Claude Code 封装程序

2. Chrome 扩展会按名称请求原生宿主

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

4. 错误的二进制文件会以 MCP 客户端不期望的格式或位置创建套接字

5. 结果：即使看起来一切都在运行，仍会出现“Browser extension is not connected”

解决方法：停用 Claude.app 的原生宿主

如果你使用 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）。

只有在确认存在冲突后，才将切换脚本作为可选的本地变通方法使用。移动任何内容前，请备份注册项并拒绝覆盖目标位置已有的文件；以下脚本仅供参考，并未实现这些检查。关闭 Chrome 可能会中断其他无关工作：重启前请保留标签页和表单，并征得授权。诊断用的进程参数或配置可能包含私人路径或值；分享前请先脱敏。未经明确请求，不要将切换脚本添加到 shell 启动配置中。

快速诊断

# 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. Preserve existing wrapper/configuration and use the installed client's supported repair.
# Do not select an executable by directory modification time or overwrite a working wrapper.

# 3. Inspect exact host PID and socket ownership/path first.
# Stop only the confirmed process for the affected session, with approval.
# Remove only its confirmed stale socket after exit; do not recursively delete bridge directories.

# 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 扩展，每个配置文件都会启动自己的原生宿主和套接字。这可能造成混淆。

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

多个 Claude Code 会话

同时运行多个 Claude Code 实例可能会导致套接字冲突。

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

包装器中的硬编码版本

~/.claude/chrome/chrome-native-host 中的包装器可能包含硬编码版本，更新后会变得过时。

诊断：

cat ~/.claude/chrome/chrome-native-host
# Bad: exec "/Users/.../.local/share/claude/versions/2.0.76" --chrome-native-host
# Verify the target is the intended installed version; modification time is not version ordering.

修复： 使用受支持的客户端修复功能重新生成包装器；保留备份，并在更改前确认目标可执行文件。

未设置 TMPDIR

Claude Code 需要设置 TMPDIR 才能找到套接字。

# 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 进行增强和更新。

限制

• 仅当任务明确符合上述范围时，才使用此技能。
• 不要将输出视为可替代针对具体环境的验证、测试或专家审核。
• 如果缺少必要的输入、权限、安全边界或成功标准，请停止并请求澄清。