trailofbits/chrome-mcp-troubleshooting

Solución de problemas de MCP de Claude en Chrome

Usa esta habilidad cuando las herramientas MCP de Claude en Chrome no se conecten o funcionen de manera poco fiable.

Cuándo usarlo

• Las herramientas mcp__claude-in-chrome__* fallan con el mensaje "Browser extension is not connected" (La extensión del navegador no está conectada)
• La automatización del navegador funciona de forma errática o agota el tiempo de espera
• Después de actualizar Claude Code o Claude.app
• Al cambiar entre Claude Code CLI y Claude.app (Cowork)
• El proceso nativo host está en ejecución pero las herramientas MCP siguen fallando

Cuándo NO usarlo

• Usuarios de Linux o Windows: Esta habilidad cubre rutas y herramientas específicas de macOS (~/Library/Application Support/, osascript)
• Problemas generales de automatización de Chrome no relacionados con la extensión de Claude
• Problemas de la aplicación de escritorio Claude.app (no relacionados con el navegador)
• Problemas de conectividad de red
• Problemas de instalación de la extensión de Chrome (usa el soporte de Chrome Web Store)

El conflicto entre Claude.app y Claude Code (Problema principal)

Antecedentes: Cuando Claude.app añadió soporte para Cowork (automatización del navegador desde la aplicación de escritorio), introdujo un host de mensajería nativa competidor que entra en conflicto con Claude Code CLI.

Dos hosts nativos, dos formatos de socket

Componente	Binario del host nativo	Ubicación del 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 (archivo único)

Por qué entran en conflicto

1. Ambos registran configuraciones de mensajería nativa en Chrome:

   • com.anthropic.claude_browser_extension.json → Ayudante de Claude.app
   • com.anthropic.claude_code_browser_extension.json → Wrapper de Claude Code

2. La extensión de Chrome solicita un host nativo por nombre

3. Si la configuración incorrecta está activa, se ejecuta el binario incorrecto

4. El binario incorrecto crea sockets en un formato/ubicación que el cliente MCP no espera

5. Resultado: "Browser extension is not connected" aunque todo parezca estar funcionando

La solución: Deshabilitar el host nativo de Claude.app

Si usas Claude Code CLI para la automatización del navegador (no Cowork):

# Deshabilitar la configuración de mensajería nativa 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

# Asegurarse de que la configuración de Claude Code existe y apunta al wrapper
cat ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json

Si usas Cowork (Claude.app) para la automatización del navegador:

# Deshabilitar la configuración de mensajería nativa 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

No puedes usar ambos simultáneamente. Elige uno y deshabilita el otro.

Script de alternancia

Añade esto a ~/.zshrc o ejecútalo directamente:

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
        # Actualmente usando Claude.app, cambiar a Claude Code
        mv "$CLAUDE_APP" "$CLAUDE_APP.disabled"
        [[ -f "$CLAUDE_CODE.disabled" ]] && mv "$CLAUDE_CODE.disabled" "$CLAUDE_CODE"
        echo "Cambiado a Claude Code CLI"
        echo "Reinicia Chrome y Claude Code para aplicar"
    elif [[ -f "$CLAUDE_CODE" && ! -f "$CLAUDE_CODE.disabled" ]]; then
        # Actualmente usando Claude Code, cambiar a Claude.app
        mv "$CLAUDE_CODE" "$CLAUDE_CODE.disabled"
        [[ -f "$CLAUDE_APP.disabled" ]] && mv "$CLAUDE_APP.disabled" "$CLAUDE_APP"
        echo "Cambiado a Claude.app (Cowork)"
        echo "Reinicia Chrome para aplicar"
    else
        echo "Estado actual no claro. Revisa las configuraciones:"
        ls -la "$CONFIG_DIR"/com.anthropic*.json* 2>/dev/null
    fi
}

Uso: chrome-mcp-toggle y luego reinicia Chrome (y Claude Code si cambias a CLI).

Diagnóstico rápido

# 1. ¿Qué binario del host nativo está en ejecución?
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. ¿Dónde está el socket?
# Para Claude Code (archivo único en TMPDIR):
ls -la "$(getconf DARWIN_USER_TEMP_DIR)/claude-mcp-browser-bridge-$USER" 2>&1

# Para Claude.app (directorio con archivos PID):
ls -la /tmp/claude-mcp-browser-bridge-$USER/ 2>&1

# 3. ¿A qué está conectado el host nativo?
lsof -U 2>&1 | grep claude-mcp-browser-bridge

# 4. ¿Qué configuraciones están activas?
ls ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic*.json

Información crítica

MCP se conecta al inicio. Si el puente del navegador no estaba listo cuando se inició Claude Code, la conexión fallará durante toda la sesión. La solución suele ser: asegurarse de que Chrome + la extensión estén funcionando con la configuración correcta, LUEGO reiniciar Claude Code.

Procedimiento de reinicio completo (Claude Code CLI)

# 1. Asegurarse de que la configuración correcta esté activa
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. Actualizar el wrapper para usar la última versión 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. Matar el host nativo existente y limpiar los 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. Reiniciar Chrome
osascript -e 'quit app "Google Chrome"' && sleep 2 && open -a "Google Chrome"

# 5. Esperar a Chrome, hacer clic en el icono de la extensión Claude

# 6. Verificar que el host nativo correcto esté en ejecución
ps aux | grep chrome-native-host | grep -v grep
# Debería mostrar: ~/.local/share/claude/versions/X.X.X --chrome-native-host

# 7. Verificar que el socket existe
ls -la "$(getconf DARWIN_USER_TEMP_DIR)/claude-mcp-browser-bridge-$USER"

# 8. Reiniciar Claude Code

Otras causas comunes

Múltiples perfiles de Chrome

Si tienes la extensión de Claude instalada en varios perfiles de Chrome, cada uno genera su propio host nativo y socket. Esto puede causar confusión.

Solución: Habilita la extensión de Claude solo en UN perfil de Chrome.

Múltiples sesiones de Claude Code

Ejecutar múltiples instancias de Claude Code puede causar conflictos de socket.

Solución: Ejecuta solo una sesión de Claude Code a la vez, o usa /mcp para reconectarte después de cerrar otras sesiones.

Versión hardcodeada en el wrapper

El wrapper en ~/.claude/chrome/chrome-native-host puede tener una versión hardcodeada que se vuelva obsoleta después de las actualizaciones.

Diagnóstico:

cat ~/.claude/chrome/chrome-native-host
# Malo: exec "/Users/.../.local/share/claude/versions/2.0.76" --chrome-native-host
# Bueno: Usa $(ls -t ...) para encontrar la última versión

Solución: Usa el wrapper de versión dinámica que se muestra en el Procedimiento de reinicio completo anterior.

TMPDIR no configurado

Claude Code espera que TMPDIR esté configurado para encontrar el socket.

# Verificar
echo $TMPDIR
# Debería mostrar: /var/folders/XX/.../T/

# Solución: Añadir a ~/.zshrc
export TMPDIR="${TMPDIR:-$(getconf DARWIN_USER_TEMP_DIR)}"

Diagnóstico en profundidad

echo "=== Binario del host nativo ==="
ps aux | grep chrome-native-host | grep -v grep

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

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

echo -e "\n=== Archivos abiertos del host nativo ==="
pgrep -f chrome-native-host | xargs -I {} lsof -p {} 2>/dev/null | grep -E "(sock|claude-mcp)"

echo -e "\n=== Configuraciones de mensajería nativa activas ==="
ls ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic*.json 2>/dev/null

echo -e "\n=== Contenido del wrapper personalizado ==="
cat ~/.claude/chrome/chrome-native-host 2>/dev/null || echo "No hay wrapper personalizado"

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

Referencia de archivos

Archivo	Propósito
~/.claude/chrome/chrome-native-host	Script wrapper personalizado para Claude Code
/Applications/Claude.app/Contents/Helpers/chrome-native-host	Host nativo de Claude.app (Cowork)
~/.local/share/claude/versions/<version>	Binario de Claude Code (ejecutar con --chrome-native-host)
~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_browser_extension.json	Configuración para el host nativo de Claude.app
~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json	Configuración para el host nativo de Claude Code
$TMPDIR/claude-mcp-browser-bridge-$USER	Archivo de socket (Claude Code)
/tmp/claude-mcp-browser-bridge-$USER/<PID>.sock	Archivos de socket (Claude.app)

Resumen

1. Problema principal: Claude.app (Cowork) y Claude Code utilizan hosts nativos diferentes con formatos de socket incompatibles
2. Solución: Deshabilitar la configuración de mensajería nativa del que NO estés usando
3. Después de cualquier solución: Debes reiniciar Chrome Y Claude Code (MCP se conecta al inicio)
4. Un perfil: Ten la extensión de Claude solo en un perfil de Chrome
5. Una sesión: Ejecuta solo una instancia de Claude Code a la vez

---

Habilidad original de @jeffzwang de @ExaAILabs. Mejorada y actualizada para las versiones actuales de Claude Desktop y Claude Code.