trailofbits/chrome-mcp-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 線上應用程式商店支援）

Claude.app 與 Claude Code 的衝突（主要問題）

背景： 當 Claude.app 加入 Cowork 支援（從桌面應用程式進行瀏覽器自動化）時，它引入了一個與 Claude Code CLI 衝突的原生訊息傳遞主機。

兩個原生主機，兩種 Socket 格式

元件	原生主機執行檔	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 中註冊了原生訊息傳遞設定：

   • com.anthropic.claude_browser_extension.json → Claude.app 輔助程式
   • com.anthropic.claude_code_browser_extension.json → Claude Code 包裝腳本

2. Chrome 擴充功能會根據名稱請求原生主機

3. 如果啟用了錯誤的設定，就會執行錯誤的執行檔

4. 錯誤的執行檔會以 MCP 用戶端不預期的格式或位置建立 socket

5. 結果：即使一切看似正常執行，仍會出現「Browser extension is not connected」

解決方案：停用 Claude.app 的原生主機

如果你使用 Claude Code CLI 進行瀏覽器自動化（而非 Cowork）：

# 停用 Claude.app 的原生訊息傳遞設定
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 Code 的設定存在並指向包裝腳本
cat ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json

如果你使用 Cowork（Claude.app）進行瀏覽器自動化：

# 停用 Claude Code 的原生訊息傳遞設定
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
        # 目前使用 Claude.app，切換至 Claude Code
        mv "$CLAUDE_APP" "$CLAUDE_APP.disabled"
        [[ -f "$CLAUDE_CODE.disabled" ]] && mv "$CLAUDE_CODE.disabled" "$CLAUDE_CODE"
        echo "已切換至 Claude Code CLI"
        echo "請重新啟動 Chrome 與 Claude Code 以套用變更"
    elif [[ -f "$CLAUDE_CODE" && ! -f "$CLAUDE_CODE.disabled" ]]; then
        # 目前使用 Claude Code，切換至 Claude.app
        mv "$CLAUDE_CODE" "$CLAUDE_CODE.disabled"
        [[ -f "$CLAUDE_APP.disabled" ]] && mv "$CLAUDE_APP.disabled" "$CLAUDE_APP"
        echo "已切換至 Claude.app (Cowork)"
        echo "請重新啟動 Chrome 以套用變更"
    else
        echo "目前狀態不明，請檢查設定："
        ls -la "$CONFIG_DIR"/com.anthropic*.json* 2>/dev/null
    fi
}

用法：執行 chrome-mcp-toggle，然後重新啟動 Chrome（若切換至 CLI 則需一併重啟 Claude Code）。

快速診斷

# 1. 哪個原生主機執行檔正在執行？
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. socket 在哪裡？
# 若使用 Claude Code（TMPDIR 中的單一檔案）：
ls -la "$(getconf DARWIN_USER_TEMP_DIR)/claude-mcp-browser-bridge-$USER" 2>&1

# 若使用 Claude.app（包含 PID 檔案的目錄）：
ls -la /tmp/claude-mcp-browser-bridge-$USER/ 2>&1

# 3. 原生主機連線到什麼？
lsof -U 2>&1 | grep claude-mcp-browser-bridge

# 4. 哪些設定是啟用的？
ls ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic*.json

關鍵見解

MCP 在啟動時連線。 如果啟動 Claude Code 時瀏覽器橋接器尚未就緒，整個工作階段的連線都會失敗。修復方法通常是：確保 Chrome 與擴充功能使用正確的設定執行，然後再重新啟動 Claude Code。

完整重置程序（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

# 2. 更新包裝腳本以使用最新版本的 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

# 3. 終止現有原生主機並清理 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"

# 4. 重新啟動 Chrome
osascript -e 'quit app "Google Chrome"' && sleep 2 && open -a "Google Chrome"

# 5. 等待 Chrome 啟動，點擊 Claude 擴充功能圖示

# 6. 確認正確的原生主機正在執行
ps aux | grep chrome-native-host | grep -v grep
# 應顯示：~/.local/share/claude/versions/X.X.X --chrome-native-host

# 7. 確認 socket 存在
ls -la "$(getconf DARWIN_USER_TEMP_DIR)/claude-mcp-browser-bridge-$USER"

# 8. 重新啟動 Claude Code

其他常見原因

多個 Chrome 設定檔

如果你在多個 Chrome 設定檔中安裝了 Claude 擴充功能，每個設定檔都會產生自己的原生主機和 socket。這可能導致混亂。

解決方法： 只在一個 Chrome 設定檔中啟用 Claude 擴充功能。

多個 Claude Code 工作階段

執行多個 Claude Code 實例可能會導致 socket 衝突。

解決方法： 一次只執行一個 Claude Code 工作階段，或在關閉其他工作階段後使用 /mcp 重新連線。

包裝腳本中寫死版本號

~/.claude/chrome/chrome-native-host 包裝腳本中可能寫死了版本號，導致更新後無法使用。

診斷方法：

cat ~/.claude/chrome/chrome-native-host
# 錯誤範例：exec "/Users/.../.local/share/claude/versions/2.0.76" --chrome-native-host
# 正確範例：使用 $(ls -t ...) 動態尋找最新版本

解決方法： 使用上述「完整重置程序」中的動態版本包裝腳本。

TMPDIR 未設定

Claude Code 預期 TMPDIR 已設定，以便找到 socket。

# 檢查
echo $TMPDIR
# 應顯示：/var/folders/XX/.../T/

# 修復：加入 ~/.zshrc
export TMPDIR="${TMPDIR:-$(getconf DARWIN_USER_TEMP_DIR)}"

深入診斷

echo "=== 原生主機執行檔 ==="
ps aux | grep chrome-native-host | grep -v grep

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

echo -e "\n=== Socket（Claude.app 位置）==="
ls -la /tmp/claude-mcp-browser-bridge-$USER/ 2>&1

echo -e "\n=== 原生主機開啟的檔案 ==="
pgrep -f chrome-native-host | xargs -I {} lsof -p {} 2>/dev/null | grep -E "(sock|claude-mcp)"

echo -e "\n=== 啟用的原生訊息傳遞設定 ==="
ls ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic*.json 2>/dev/null

echo -e "\n=== 自訂包裝腳本內容 ==="
cat ~/.claude/chrome/chrome-native-host 2>/dev/null || echo "無自訂包裝腳本"

echo -e "\n=== TMPDIR ==="
echo "TMPDIR=$TMPDIR"
echo "預期值：$(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	Socket 檔案（Claude Code）
/tmp/claude-mcp-browser-bridge-$USER/<PID>.sock	Socket 檔案（Claude.app）

總結

1. 主要問題： Claude.app (Cowork) 與 Claude Code 使用不同的原生主機，且 socket 格式不相容
2. 解決方法： 停用你未使用的那個原生訊息傳遞設定
3. 任何修復後： 必須重新啟動 Chrome 和 Claude Code（MCP 在啟動時連線）
4. 一個設定檔： 只在一個 Chrome 設定檔中啟用 Claude 擴充功能
5. 一個工作階段： 只執行一個 Claude Code 實例

---

原版技能由 @jeffzwang 來自 @ExaAILabs 製作。針對 Claude Desktop 和 Claude Code 的現行版本進行了強化與更新。