Puppeteer MCP Server

Automatize interações do navegador usando Puppeteer, controlando instâncias novas ou existentes do Chrome.

GitHub
484
Experimente este MCPPatrocinado

Documentação

Puppeteer MCP Server

smithery badge Este servidor MCP fornece capacidades de automação de navegador através do Puppeteer, permitindo interação tanto com novas instâncias de navegador quanto com janelas existentes do Chrome.

Reconhecimento

Este projeto é uma implementação experimental inspirada em @modelcontextprotocol/server-puppeteer. Embora compartilhe objetivos e conceitos semelhantes, explora abordagens alternativas para automação de navegador através do Model Context Protocol.

Puppeteer Server MCP server

Recursos

  • Navegar em páginas da web
  • Tirar capturas de tela
  • Clicar em elementos
  • Preencher formulários
  • Selecionar opções
  • Passar o mouse sobre elementos
  • Executar JavaScript
  • Gerenciamento inteligente de abas do Chrome:
    • Conectar-se a abas ativas do Chrome
    • Preservar instâncias existentes do Chrome
    • Tratamento inteligente de conexões

Estrutura do Projeto

/
├── src/
│   ├── config/        # Configuration modules
│   ├── tools/         # Tool definitions and handlers
│   ├── browser/       # Browser connection management
│   ├── types/         # TypeScript type definitions
│   ├── resources/     # Resource handlers
│   └── server.ts      # Server initialization
├── index.ts          # Entry point
└── README.md        # Documentation

Instalação

Opção 1: Instalar a partir do npm

npm install -g puppeteer-mcp-server

Você também pode executá-lo diretamente sem instalação usando npx:

npx puppeteer-mcp-server

Opção 2: Instalar a partir do código-fonte

  1. Clone este repositório ou baixe o código-fonte
  2. Instale as dependências:
npm install
  1. Compile o projeto:
npm run build
  1. Execute o servidor:
npm start

Configuração do Servidor MCP

Para usar esta ferramenta com o Claude, você precisa adicioná-la ao seu arquivo de configuração de configurações MCP.

Para o aplicativo Claude Desktop

Adicione o seguinte ao seu arquivo de configuração do Claude Desktop (localizado em %APPDATA%\Claude\claude_desktop_config.json no Windows ou ~/Library/Application Support/Claude/claude_desktop_config.json no macOS):

Se instalado globalmente via npm:

{
  "mcpServers": {
    "puppeteer": {
      "command": "puppeteer-mcp-server",
      "args": [],
      "env": {}
    }
  }
}

Usando npx (sem instalação):

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "puppeteer-mcp-server"],
      "env": {}
    }
  }
}

Se instalado a partir do código-fonte:

{
  "mcpServers": {
    "puppeteer": {
      "command": "node",
      "args": ["path/to/puppeteer-mcp-server/dist/index.js"],
      "env": {
        "NODE_OPTIONS": "--experimental-modules"
      }
    }
  }
}

Para a extensão Claude VSCode

Adicione o seguinte ao seu arquivo de configurações MCP da extensão Claude VSCode (localizado em %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json no Windows ou ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json no macOS):

Se instalado globalmente via npm:

{
  "mcpServers": {
    "puppeteer": {
      "command": "puppeteer-mcp-server",
      "args": [],
      "env": {}
    }
  }
}

Usando npx (sem instalação):

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "puppeteer-mcp-server"],
      "env": {}
    }
  }
}

Se instalado a partir do código-fonte:

{
  "mcpServers": {
    "puppeteer": {
      "command": "node",
      "args": ["path/to/puppeteer-mcp-server/dist/index.js"],
      "env": {
        "NODE_OPTIONS": "--experimental-modules"
      }
    }
  }
}

Para instalação a partir do código-fonte, substitua path/to/puppeteer-mcp-server pelo caminho real onde você instalou esta ferramenta.

Uso

Modo Padrão

O servidor iniciará uma nova instância do navegador por padrão.

Modo de Aba Ativa

Para conectar-se a uma janela existente do Chrome:

  1. Feche completamente quaisquer instâncias existentes do Chrome

  2. Inicie o Chrome com depuração remota habilitada:

    # Windows
"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

# Linux
google-chrome --remote-debugging-port=9222

  3. Navegue até a página da web desejada no Chrome

  4. Conecte-se usando a ferramenta puppeteer_connect_active_tab:

    {
  "targetUrl": "https://example.com", // Optional: specific tab URL
  "debugPort": 9222 // Optional: defaults to 9222
}

O servidor irá:

  • Detectar e conectar-se à instância do Chrome executando com depuração remota habilitada
  • Preservar sua instância do Chrome (não a fechará)
  • Encontrar e conectar-se a abas que não sejam de extensões
  • Fornecer mensagens de erro claras se a conexão falhar

Ferramentas Disponíveis

puppeteer_connect_active_tab

Conecte-se a uma instância existente do Chrome com depuração remota habilitada.

  • Opcionais:
    • targetUrl - URL da aba específica à qual conectar
    • debugPort - Porta de depuração do Chrome (padrão: 9222)

puppeteer_navigate

Navegue para uma URL.

  • Obrigatório: url - A URL para navegar

puppeteer_screenshot

Tire uma captura de tela da página atual ou de um elemento específico.

  • Obrigatório: name - Nome para a captura de tela
  • Opcionais:
    • selector - Seletor CSS do elemento para capturar
    • width - Largura em pixels (padrão: 800)
    • height - Altura em pixels (padrão: 600)

puppeteer_click

Clique em um elemento na página.

  • Obrigatório: selector - Seletor CSS do elemento para clicar

puppeteer_fill

Preencha um campo de entrada.

  • Obrigatórios:
    • selector - Seletor CSS do campo de entrada
    • value - Texto a inserir

puppeteer_select

Use menus suspensos.

  • Obrigatórios:
    • selector - Seletor CSS do elemento select
    • value - Valor da opção a selecionar

puppeteer_hover

Passe o mouse sobre elementos.

  • Obrigatório: selector - Seletor CSS do elemento para passar o mouse

puppeteer_evaluate

Execute JavaScript no console do navegador.

  • Obrigatório: script - Código JavaScript a executar

Considerações de Segurança

Ao usar depuração remota:

  • Habilite apenas em redes confiáveis
  • Use uma porta de depuração exclusiva
  • Feche a porta de depuração quando não estiver em uso
  • Nunca exponha a porta de depuração a redes públicas

Registro e Depuração

Registro Baseado em Arquivos

O servidor implementa registro abrangente usando Winston:

  • Localização: diretório logs/
  • Padrão de Arquivo: mcp-puppeteer-YYYY-MM-DD.log
  • Rotação de Registros:
    • Rotação diária
    • Tamanho máximo: 20MB por arquivo
    • Retenção: 14 dias
    • Compressão automática de registros antigos

Níveis de Registro

  • DEBUG: Informações detalhadas de depuração
  • INFO: Informações operacionais gerais
  • WARN: Mensagens de aviso
  • ERROR: Eventos de erro e exceções

Informações Registradas

  • Eventos de inicialização/desligamento do servidor
  • Operações do navegador (inicialização, conexão, fechamento)
  • Tentativas e resultados de navegação
  • Execuções e resultados de ferramentas
  • Detalhes de erro com rastreamentos de pilha
  • Saída do console do navegador
  • Uso de recursos (capturas de tela, registros de console)

Tratamento de Erros

O servidor fornece mensagens de erro detalhadas para:

  • Falhas de conexão
  • Elementos ausentes
  • Seletores inválidos
  • Erros de execução de JavaScript
  • Falhas de captura de tela

Cada chamada de ferramenta retorna:

  • Status de sucesso/falha
  • Mensagem de erro detalhada se falhar
  • Dados de resultado da operação se for bem-sucedida

Todos os erros também são registrados nos arquivos de registro com:

  • Carimbo de data/hora
  • Mensagem de erro
  • Rastreamento de pilha (quando disponível)
  • Informações de contexto

Contribuindo

Contribuições são bem-vindas! Leia nossas Diretrizes de Contribuição para detalhes sobre como enviar pull requests, relatar problemas e contribuir com o projeto.

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.