Chrome Debug MCP Server

Automatize seu navegador conectando-se à porta de depuração do Chrome, preservando seu estado de login.

GitHub
10
Experimente este MCPPatrocinado

Documentação

Chrome Debug MCP Server

Idioma: English | 中文

Um servidor Model Context Protocol (MCP) para automação do navegador Chrome via protocolo de depuração, projetado especificamente para conectar-se a portas de depuração do Chrome e permitir automação do navegador com sessões de login persistentes.

🎯 Vantagens do Projeto

🚀 Vantagens Técnicas Principais

  1. 🔧 Implantação com Zero Dependências

    • Nenhuma extensão do Chrome necessária
    • Nenhuma aprovação da Chrome Web Store necessária
    • Totalmente autônomo em ambientes corporativos

  2. 📦 Compatível com Contêineres

    • Suporte perfeito para implantação em Docker/Kubernetes
    • Sem problemas de permissão ou instalação de extensões
    • Ideal para arquitetura cloud-native

  3. ⚡ Inicialização em Duas Etapas

    # Launch with just two commands
# 1. Start Chrome in debug mode
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug
# 2. Run MCP server
npx chrome-debug-mcp

  4. 🛡️ Segurança de Nível Empresarial

    • Baseado no protocolo padrão Chrome DevTools
    • Nenhuma permissão de extensão de terceiros necessária
    • Operação completamente local

🚀 Início Rápido

Opção 1: Uso Direto (Recomendado)

Inicie com npx - nenhuma instalação necessária:

# 1. Start Chrome in debug mode
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug

# 2. Run MCP server directly
npx chrome-debug-mcp

Opção 2: Desenvolvimento Local

git clone https://github.com/rainmenxia/chrome-debug-mcp.git
cd chrome-debug-mcp
npm install
npm run build
npm start

Recursos Principais

  • ✅ Conexão com Porta de Depuração do Chrome: Baseado no protocolo padrão Chrome DevTools, sem necessidade de extensões
  • 🏢 Implantação de Nível Empresarial: Implantação com zero dependências, sem necessidade de aprovação da Chrome Web Store
  • 📱 Gerenciamento Inteligente de Abas: Reutiliza abas para os mesmos domínios, evita aberturas duplicadas
  • 🖼️ Feedback de Captura de Tela em Tempo Real: Capturas automáticas após cada operação para feedback visual
  • 🌐 Monitoramento de Atividade de Rede: Aguarda automaticamente a conclusão do carregamento da página
  • 🐳 Suporte Nativo a Docker: Suporte perfeito para instâncias do Chrome em contêineres, sem limitações de extensões
  • ⚡ Inicialização em Duas Etapas: Inicie o Chrome em modo de depuração e depois execute npx chrome-debug-mcp, sem instalação complexa
  • 🔍 Descoberta Inteligente de Navegador: Descobre automaticamente instâncias do Chrome em ambientes locais e Docker

Configuração e Uso

1. Iniciar o Chrome em Modo de Depuração (Obrigatório)

O servidor precisa se conectar a uma instância do Chrome com a porta de depuração habilitada:

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug

# Windows
chrome.exe --remote-debugging-port=9222 --user-data-dir=c:\temp\chrome-debug

# Linux
google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug

Notas Importantes:

  • O parâmetro --user-data-dir aponta para um diretório temporário, garantindo que o Chrome inicie em modo de depuração
  • Após a inicialização, você pode fazer login em sites normalmente, e as sessões de login serão preservadas
  • O servidor reutilizará esta instância do Chrome, sem necessidade de novo login

2. Configurar o Cliente MCP

Adicione a seguinte configuração ao seu cliente MCP:

{
  "mcpServers": {
    "browser-automation": {
      "command": "npx",
      "args": ["chrome-debug-mcp"]
    }
  }
}

Pronto! Sem instalação, sem downloads, sem necessidade de configuração complexa de caminhos.

💡 Métodos Alternativos de Instalação:

Instalação Global:

npm install -g chrome-debug-mcp

{
  "mcpServers": {
    "browser-automation": {
      "command": "chrome-debug-mcp"
    }
  }
}

Instalação em Projeto Local:

npm install chrome-debug-mcp

{
  "mcpServers": {
    "browser-automation": {
      "command": "npx",
      "args": ["chrome-debug-mcp"]
    }
  }
}

Ferramentas Disponíveis

1. launch_browser

Conecta-se à porta de depuração do Chrome e inicializa a sessão do navegador.

{
  "name": "launch_browser",
  "arguments": {
    "remote_host": "http://localhost:9222"  // optional
  }
}

2. navigate_to

Navega para uma URL especificada com gerenciamento inteligente de abas.

{
  "name": "navigate_to", 
  "arguments": {
    "url": "https://example.com"
  }
}

3. click

Clica em coordenadas especificadas.

{
  "name": "click",
  "arguments": {
    "coordinate": "100,200"
  }
}

4. type_text

Insere conteúdo de texto.

{
  "name": "type_text",
  "arguments": {
    "text": "Hello World"
  }
}

5. scroll_down / scroll_up

Rola a página.

{
  "name": "scroll_down",
  "arguments": {}
}

6. hover

Posiciona o mouse em uma posição especificada.

{
  "name": "hover",
  "arguments": {
    "coordinate": "100,200"
  }
}

7. resize_browser

Redimensiona a janela do navegador.

{
  "name": "resize_browser",
  "arguments": {
    "size": "1200,800"
  }
}

8. get_page_content

Obtém o conteúdo HTML atual da página.

{
  "name": "get_page_content",
  "arguments": {}
}

9. close_browser

Fecha a conexão do navegador.

{
  "name": "close_browser",
  "arguments": {}
}

Casos de Uso Típicos

1. Automação de Mídias Sociais

# Manually log into Twitter/Weibo in Chrome first
# Then use MCP tools for automation
launch_browser -> navigate_to -> click -> type_text

2. Operações de E-commerce

# Keep logged-in state for Taobao/JD
# Automate product search, price monitoring, etc.
launch_browser -> navigate_to -> type_text -> click

3. Coleta de Dados

# Scrape data from login-required websites
# Bypass login verification, direct operations
launch_browser -> navigate_to -> get_page_content

Recursos Avançados

Gerenciamento Inteligente de Abas

  • Mesmos domínios (ex.: example.com) reutilizam abas existentes
  • Domínios diferentes criam novas abas automaticamente
  • Evita aberturas duplicadas dos mesmos sites

Mecanismos de Espera Automática

  • Monitora a atividade de rede, aguarda o carregamento completo da página
  • Detecção de estabilidade do conteúdo HTML
  • Tratamento automático de carregamento de conteúdo dinâmico

Recuperação de Erros

  • Reconexão automática em caso de queda de conexão
  • Cache de endpoints de conexão bem-sucedidos
  • Logs de erro detalhados e feedback

Suporte a Ambientes Docker

Se o Chrome estiver em execução em um contêiner Docker:

# Start Chrome in Docker
docker run -d --name chrome-debug \
  -p 9222:9222 \
  --shm-size=2gb \
  zenika/alpine-chrome \
  --no-sandbox \
  --disable-dev-shm-usage \
  --remote-debugging-address=0.0.0.0 \
  --remote-debugging-port=9222

O servidor descobrirá automaticamente instâncias do Chrome em ambientes Docker.

Solução de Problemas

Falha na Conexão com o Chrome

  1. Confirme que o Chrome foi iniciado com --remote-debugging-port=9222
  2. Verifique se a porta 9222 está ocupada: lsof -i :9222
  3. Certifique-se de que nenhuma outra instância do Chrome esteja em execução

Tempo Limite de Operação

  1. Verifique a conexão de rede
  2. Aumente o tempo limite de carregamento da página
  3. Confirme se o site de destino está acessível

Falha na Captura de Tela

  1. Confirme que a página está totalmente carregada
  2. Verifique as configurações de tamanho da janela do navegador
  3. Tente atualizar a página e repetir a operação

Arquitetura Técnica

MCP Client ←→ stdio ←→ MCP Server ←→ Chrome Debug Port ←→ Chrome Browser
  • Protocolo de Transporte: stdio (entrada/saída padrão)
  • Mecanismo do Navegador: Puppeteer + Chrome DevTools Protocol
  • Método de Conexão: WebSocket (porta de depuração do Chrome)
  • Formato de Imagem: codificação base64 WebP/PNG

Desenvolvimento e Depuração

# Watch mode compilation
npm run dev

# View MCP communication logs
DEBUG=mcp* npm start

Publicação no npm

# Build project
npm run build

# Publish to npm
npm publish

Agradecimentos

A filosofia de design e os conceitos principais deste projeto foram inspirados no projeto RooCode. RooCode é uma excelente implementação de servidor MCP de automação de navegador que forneceu referências técnicas valiosas e insights de design.

Agradecimentos especiais à equipe do RooCode por suas contribuições nas seguintes áreas:

  • 🎯 Integração com Protocolo MCP: Forneceu soluções técnicas para combinar servidores MCP com automação de navegador
  • 🔗 Conexão com o Navegador: Demonstrou gerenciamento elegante de conexão e sessão do navegador
  • 📋 Design de API de Ferramentas: Forneceu estruturas de referência para padronizar operações do navegador

Com base na fundação do RooCode, este projeto foca ainda mais em automação de navegador com sessões de login persistentes, alcançando capacidades de automação mais práticas ao conectar-se a portas de depuração existentes do Chrome para manter as sessões do usuário.

Licença

Licença MIT

Vantagem Principal: A maior característica deste servidor MCP é sua capacidade de conectar-se a instâncias existentes do Chrome e manter sessões de login, tornando-o ideal para cenários de automação que exigem autenticação do usuário. Através das portas de depuração do Chrome, ele pode assumir sessões de navegador com login do usuário, alcançando verdadeira automação de navegador com "sessão persistente".