trailofbits/chrome-mcp-troubleshooting

Solução de Problemas do MCP do Claude no Chrome

Use esta skill quando as ferramentas MCP do Claude no Chrome falharem ao conectar ou funcionarem de forma não confiável.

Quando Usar

• Ferramentas mcp__claude-in-chrome__* falham com "A extensão do navegador não está conectada"
• A automação do navegador funciona erraticamente ou atinge tempo limite
• Após atualizar o Claude Code ou Claude.app
• Ao alternar entre Claude Code CLI e Claude.app (Cowork)
• O processo host nativo está rodando, mas as ferramentas MCP ainda falham

Quando NÃO Usar

• Usuários de Linux ou Windows - Esta skill cobre caminhos e ferramentas específicos do macOS (~/Library/Application Support/, osascript)
• Problemas gerais de automação do Chrome não relacionados à extensão Claude
• Problemas do aplicativo Claude.app para desktop (não relacionados ao navegador)
• Problemas de conectividade de rede
• Problemas de instalação da extensão do Chrome (use o suporte da Chrome Web Store)

O Conflito Claude.app vs Claude Code (Problema Principal)

Contexto: Quando o Claude.app adicionou suporte a Cowork (automação do navegador a partir do aplicativo desktop), ele introduziu um host de mensagens nativas concorrente que entra em conflito com o Claude Code CLI.

Dois Hosts Nativos, Dois Formatos de Socket

Componente	Binário do Host Nativo	Localização do 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/<versao> --chrome-native-host	$TMPDIR/claude-mcp-browser-bridge-$USER (arquivo único)

Por Que Eles Conflitam

1. Ambos registram configurações de mensagens nativas no Chrome:

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

2. A extensão do Chrome solicita um host nativo pelo nome

3. Se a configuração errada estiver ativa, o binário errado é executado

4. O binário errado cria sockets em um formato/localização que o cliente MCP não espera

5. Resultado: "A extensão do navegador não está conectada" mesmo que tudo pareça estar rodando

A Correção: Desabilitar o Host Nativo do Claude.app

Se você usa Claude Code CLI para automação do navegador (não Cowork):

# Desabilita a configuração de mensagens nativas do 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

# Garante que a configuração do Claude Code existe e aponta para o wrapper
cat ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json

Se você usa Cowork (Claude.app) para automação do navegador:

# Desabilita a configuração de mensagens nativas do 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

Você não pode usar ambos simultaneamente. Escolha um e desabilite o outro.

Script de Alternância (Toggle)

Adicione ao ~/.zshrc ou execute diretamente:

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
        # Atualmente usando Claude.app, alternar para Claude Code
        mv "$CLAUDE_APP" "$CLAUDE_APP.disabled"
        [[ -f "$CLAUDE_CODE.disabled" ]] && mv "$CLAUDE_CODE.disabled" "$CLAUDE_CODE"
        echo "Alternado para Claude Code CLI"
        echo "Reinicie o Chrome e o Claude Code para aplicar"
    elif [[ -f "$CLAUDE_CODE" && ! -f "$CLAUDE_CODE.disabled" ]]; then
        # Atualmente usando Claude Code, alternar para Claude.app
        mv "$CLAUDE_CODE" "$CLAUDE_CODE.disabled"
        [[ -f "$CLAUDE_APP.disabled" ]] && mv "$CLAUDE_APP.disabled" "$CLAUDE_APP"
        echo "Alternado para Claude.app (Cowork)"
        echo "Reinicie o Chrome para aplicar"
    else
        echo "Estado atual incerto. Verifique as configurações:"
        ls -la "$CONFIG_DIR"/com.anthropic*.json* 2>/dev/null
    fi
}

Uso: chrome-mcp-toggle e depois reinicie o Chrome (e o Claude Code se estiver alternando para CLI).

Diagnóstico Rápido

# 1. Qual binário do host nativo está rodando?
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. Onde está o socket?
# Para Claude Code (arquivo único em TMPDIR):
ls -la "$(getconf DARWIN_USER_TEMP_DIR)/claude-mcp-browser-bridge-$USER" 2>&1

# Para Claude.app (diretório com arquivos PID):
ls -la /tmp/claude-mcp-browser-bridge-$USER/ 2>&1

# 3. A que o host nativo está conectado?
lsof -U 2>&1 | grep claude-mcp-browser-bridge

# 4. Quais configurações estão ativas?
ls ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic*.json

Insight Crítico

O MCP conecta na inicialização. Se a ponte do navegador não estava pronta quando o Claude Code iniciou, a conexão falhará para toda a sessão. A correção geralmente é: garantir que o Chrome + extensão estejam rodando com a configuração correta, e ENTÃO reiniciar o Claude Code.

Procedimento de Reset Completo (Claude Code CLI)

# 1. Garante que a configuração correta está ativa
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. Atualiza o wrapper para usar a versão mais recente do 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. Mata o host nativo existente e limpa 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. Reinicia o Chrome
osascript -e 'quit app "Google Chrome"' && sleep 2 && open -a "Google Chrome"

# 5. Aguarda o Chrome, clique no ícone da extensão Claude

# 6. Verifica se o host nativo correto está rodando
ps aux | grep chrome-native-host | grep -v grep
# Deve mostrar: ~/.local/share/claude/versions/X.X.X --chrome-native-host

# 7. Verifica se o socket existe
ls -la "$(getconf DARWIN_USER_TEMP_DIR)/claude-mcp-browser-bridge-$USER"

# 8. Reinicia o Claude Code

Outras Causas Comuns

Múltiplos Perfis do Chrome

Se você tiver a extensão Claude instalada em vários perfis do Chrome, cada um gera seu próprio host nativo e socket. Isso pode causar confusão.

Correção: Ative a extensão Claude em APENAS UM perfil do Chrome.

Múltiplas Sessões do Claude Code

Executar múltiplas instâncias do Claude Code pode causar conflitos de socket.

Correção: Execute apenas uma sessão do Claude Code por vez, ou use /mcp para reconectar após fechar outras sessões.

Versão Hardcoded no Wrapper

O wrapper em ~/.claude/chrome/chrome-native-host pode ter uma versão hardcoded que fica desatualizada após atualizações.

Diagnóstico:

cat ~/.claude/chrome/chrome-native-host
# Ruim: exec "/Users/.../.local/share/claude/versions/2.0.76" --chrome-native-host
# Bom: Usa $(ls -t ...) para encontrar a mais recente

Correção: Use o wrapper com versão dinâmica mostrado no Procedimento de Reset Completo acima.

TMPDIR Não Definido

O Claude Code espera que TMPDIR esteja definido para encontrar o socket.

# Verificar
echo $TMPDIR
# Deve mostrar: /var/folders/XX/.../T/

# Correção: Adicionar ao ~/.zshrc
export TMPDIR="${TMPDIR:-$(getconf DARWIN_USER_TEMP_DIR)}"

Diagnóstico Aprofundado

echo "=== Binário do Host Nativo ==="
ps aux | grep chrome-native-host | grep -v grep

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

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

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

echo -e "\n=== Configurações de Mensagens Nativas Ativas ==="
ls ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic*.json 2>/dev/null

echo -e "\n=== Conteúdo do Wrapper Personalizado ==="
cat ~/.claude/chrome/chrome-native-host 2>/dev/null || echo "Nenhum wrapper personalizado"

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

Referência de Arquivos

Arquivo	Propósito
~/.claude/chrome/chrome-native-host	Script wrapper personalizado para Claude Code
/Applications/Claude.app/Contents/Helpers/chrome-native-host	Host nativo do Claude.app (Cowork)
~/.local/share/claude/versions/<versao>	Binário do Claude Code (execute com --chrome-native-host)
~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_browser_extension.json	Configuração para o host nativo do Claude.app
~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json	Configuração para o host nativo do Claude Code
$TMPDIR/claude-mcp-browser-bridge-$USER	Arquivo de socket (Claude Code)
/tmp/claude-mcp-browser-bridge-$USER/<PID>.sock	Arquivos de socket (Claude.app)

Resumo

1. Problema principal: Claude.app (Cowork) e Claude Code usam hosts nativos diferentes com formatos de socket incompatíveis
2. Correção: Desabilite a configuração de mensagens nativas daquele que você NÃO está usando
3. Após qualquer correção: É necessário reiniciar o Chrome E o Claude Code (o MCP conecta na inicialização)
4. Um perfil: Tenha a extensão Claude em apenas um perfil do Chrome
5. Uma sessão: Execute apenas uma instância do Claude Code por vez

---

Skill original por @jeffzwang da @ExaAILabs. Aprimorada e atualizada para as versões atuais do Claude Desktop e Claude Code.