trailofbits/chrome-mcp-troubleshooting

Dépannage MCP Claude dans Chrome

Utilisez cette compétence lorsque les outils MCP Claude dans Chrome ne parviennent pas à se connecter ou fonctionnent de manière peu fiable.

Quand l'utiliser

• Les outils mcp__claude-in-chrome__* échouent avec le message "Extension navigateur non connectée"
• L'automatisation du navigateur fonctionne de manière erratique ou expire
• Après une mise à jour de Claude Code ou de Claude.app
• Lors du basculement entre Claude Code CLI et Claude.app (Cowork)
• Le processus hôte natif est en cours d'exécution mais les outils MCP échouent toujours

Quand NE PAS l'utiliser

• Utilisateurs Linux ou Windows - Cette compétence couvre les chemins et outils spécifiques à macOS (~/Library/Application Support/, osascript)
• Problèmes généraux d'automatisation Chrome non liés à l'extension Claude
• Problèmes du bureau Claude.app (non liés au navigateur)
• Problèmes de connectivité réseau
• Problèmes d'installation de l'extension Chrome (utilisez le support du Chrome Web Store)

Le conflit Claude.app vs Claude Code (problème principal)

Contexte : Lorsque Claude.app a ajouté la prise en charge de Cowork (automatisation du navigateur depuis l'application de bureau), il a introduit un hôte de messagerie natif concurrent qui entre en conflit avec Claude Code CLI.

Deux hôtes natifs, deux formats de socket

Composant	Binaire hôte natif	Emplacement du 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 (fichier unique)

Pourquoi ils entrent en conflit

1. Les deux enregistrent des configurations de messagerie native dans Chrome :

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

2. L'extension Chrome demande un hôte natif par nom

3. Si la mauvaise configuration est active, le mauvais binaire s'exécute

4. Le mauvais binaire crée des sockets dans un format/emplacement que le client MCP n'attend pas

5. Résultat : "Extension navigateur non connectée" même si tout semble fonctionner

La solution : désactiver l'hôte natif de Claude.app

Si vous utilisez Claude Code CLI pour l'automatisation du navigateur (pas Cowork) :

# Désactiver la configuration de messagerie native de 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

# Vérifier que la configuration Claude Code existe et pointe vers le wrapper
cat ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json

Si vous utilisez Cowork (Claude.app) pour l'automatisation du navigateur :

# Désactiver la configuration de messagerie native de 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

Vous ne pouvez pas utiliser les deux simultanément. Choisissez-en un et désactivez l'autre.

Script de basculement

Ajoutez ceci à ~/.zshrc ou exécutez-le directement :

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
        # Utilise actuellement Claude.app, basculer vers Claude Code
        mv "$CLAUDE_APP" "$CLAUDE_APP.disabled"
        [[ -f "$CLAUDE_CODE.disabled" ]] && mv "$CLAUDE_CODE.disabled" "$CLAUDE_CODE"
        echo "Basculement vers Claude Code CLI"
        echo "Redémarrez Chrome et Claude Code pour appliquer"
    elif [[ -f "$CLAUDE_CODE" && ! -f "$CLAUDE_CODE.disabled" ]]; then
        # Utilise actuellement Claude Code, basculer vers Claude.app
        mv "$CLAUDE_CODE" "$CLAUDE_CODE.disabled"
        [[ -f "$CLAUDE_APP.disabled" ]] && mv "$CLAUDE_APP.disabled" "$CLAUDE_APP"
        echo "Basculement vers Claude.app (Cowork)"
        echo "Redémarrez Chrome pour appliquer"
    else
        echo "État actuel incertain. Vérifiez les configurations :"
        ls -la "$CONFIG_DIR"/com.anthropic*.json* 2>/dev/null
    fi
}

Utilisation : chrome-mcp-toggle puis redémarrez Chrome (et Claude Code si vous basculez vers CLI).

Diagnostic rapide

# 1. Quel est le binaire hôte natif en cours d'exécution ?
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. Où se trouve le socket ?
# Pour Claude Code (fichier unique dans TMPDIR) :
ls -la "$(getconf DARWIN_USER_TEMP_DIR)/claude-mcp-browser-bridge-$USER" 2>&1

# Pour Claude.app (répertoire avec fichiers PID) :
ls -la /tmp/claude-mcp-browser-bridge-$USER/ 2>&1

# 3. À quoi l'hôte natif est-il connecté ?
lsof -U 2>&1 | grep claude-mcp-browser-bridge

# 4. Quelles configurations sont actives ?
ls ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic*.json

Information cruciale

MCP se connecte au démarrage. Si le pont navigateur n'était pas prêt au démarrage de Claude Code, la connexion échouera pour toute la session. La solution est généralement : assurez-vous que Chrome + l'extension sont en cours d'exécution avec la bonne configuration, PUIS redémarrez Claude Code.

Procédure de réinitialisation complète (Claude Code CLI)

# 1. Assurez-vous que la bonne configuration est 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. Mettez à jour le wrapper pour utiliser la dernière version de 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. Tuez l'hôte natif existant et nettoyez les 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. Redémarrez Chrome
osascript -e 'quit app "Google Chrome"' && sleep 2 && open -a "Google Chrome"

# 5. Attendez Chrome, cliquez sur l'icône de l'extension Claude

# 6. Vérifiez que le bon hôte natif est en cours d'exécution
ps aux | grep chrome-native-host | grep -v grep
# Devrait afficher : ~/.local/share/claude/versions/X.X.X --chrome-native-host

# 7. Vérifiez que le socket existe
ls -la "$(getconf DARWIN_USER_TEMP_DIR)/claude-mcp-browser-bridge-$USER"

# 8. Redémarrez Claude Code

Autres causes courantes

Profils Chrome multiples

Si vous avez l'extension Claude installée dans plusieurs profils Chrome, chacun génère son propre hôte natif et son propre socket. Cela peut prêter à confusion.

Solution : Activez l'extension Claude dans UN SEUL profil Chrome.

Sessions Claude Code multiples

L'exécution de plusieurs instances Claude Code peut provoquer des conflits de sockets.

Solution : N'exécutez qu'une seule session Claude Code à la fois, ou utilisez /mcp pour vous reconnecter après avoir fermé d'autres sessions.

Version codée en dur dans le wrapper

Le wrapper dans ~/.claude/chrome/chrome-native-host peut avoir une version codée en dur qui devient obsolète après les mises à jour.

Diagnostic :

cat ~/.claude/chrome/chrome-native-host
# Mauvais : exec "/Users/.../.local/share/claude/versions/2.0.76" --chrome-native-host
# Bon : utilise $(ls -t ...) pour trouver la dernière version

Solution : Utilisez le wrapper de version dynamique présenté dans la Procédure de réinitialisation complète ci-dessus.

TMPDIR non défini

Claude Code s'attend à ce que TMPDIR soit défini pour trouver le socket.

# Vérification
echo $TMPDIR
# Devrait afficher : /var/folders/XX/.../T/

# Solution : Ajoutez dans ~/.zshrc
export TMPDIR="${TMPDIR:-$(getconf DARWIN_USER_TEMP_DIR)}"

Diagnostic approfondi

echo "=== Binaire hôte natif ==="
ps aux | grep chrome-native-host | grep -v grep

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

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

echo -e "\n=== Fichiers ouverts de l'hôte natif ==="
pgrep -f chrome-native-host | xargs -I {} lsof -p {} 2>/dev/null | grep -E "(sock|claude-mcp)"

echo -e "\n=== Configurations de messagerie native actives ==="
ls ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic*.json 2>/dev/null

echo -e "\n=== Contenu du wrapper personnalisé ==="
cat ~/.claude/chrome/chrome-native-host 2>/dev/null || echo "Aucun wrapper personnalisé"

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

Référence des fichiers

Fichier	Objectif
~/.claude/chrome/chrome-native-host	Script wrapper personnalisé pour Claude Code
/Applications/Claude.app/Contents/Helpers/chrome-native-host	Hôte natif Claude.app (Cowork)
~/.local/share/claude/versions/<version>	Binaire Claude Code (exécuté avec --chrome-native-host)
~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_browser_extension.json	Configuration pour l'hôte natif Claude.app
~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json	Configuration pour l'hôte natif Claude Code
$TMPDIR/claude-mcp-browser-bridge-$USER	Fichier socket (Claude Code)
/tmp/claude-mcp-browser-bridge-$USER/<PID>.sock	Fichiers socket (Claude.app)

Résumé

1. Problème principal : Claude.app (Cowork) et Claude Code utilisent des hôtes natifs différents avec des formats de socket incompatibles
2. Solution : Désactivez la configuration de messagerie native pour celui que vous n'utilisez PAS
3. Après toute solution : Vous DEVEZ redémarrer Chrome ET Claude Code (MCP se connecte au démarrage)
4. Un seul profil : N'ayez l'extension Claude que dans un seul profil Chrome
5. Une seule session : N'exécutez qu'une seule instance Claude Code à la fois

---

Compétence originale par @jeffzwang de @ExaAILabs. Améliorée et mise à jour pour les versions actuelles de Claude Desktop et Claude Code.