Puppeteer

Automação de navegador usando Puppeteer, com suporte para implantações locais, Docker e Cloudflare Workers.

Documentação

Servidor MCP do Puppeteer

Um servidor abrangente do Model Context Protocol (MCP) que fornece capacidades de automação de navegador usando Puppeteer. Este servidor permite que Modelos de Linguagem de Grande Porte (LLMs) interajam com páginas web, tirem capturas de tela e executem JavaScript em ambientes locais e na nuvem.

🚀 Recursos

Capacidades Principais

Automação de Navegador: Navegue, clique, preencha formulários e interaja com páginas web
Captura de Screenshots: Tire capturas de tela de página inteira ou de elementos específicos
Execução de JavaScript: Execute scripts personalizados no contexto do navegador
Monitoramento de Console: Capture e acesse logs do console do navegador
Gerenciamento de Recursos: Armazene e recupere capturas de tela e logs
Controles de Segurança: Filtragem configurável de argumentos perigosos

Opções de Implantação

Desenvolvimento Local: Integração direta do Puppeteer com Chromium
Contêiner Docker: Implantação em contêiner com suporte a ARM64
Cloudflare Workers: Implantação em nuvem usando serviços de navegador externos

📦 Instalação e Uso

Opção 1: NPX (Recomendado para Desenvolvimento Local)

npx -y @modelcontextprotocol/server-puppeteer

Opção 2: Docker

docker run -i --rm --init -e DOCKER_CONTAINER=true puppeteer-mcp

Opção 3: Compilar a partir do Código Fonte

git clone https://github.com/code-craka/puppeteer-mcp.git
cd puppeteer-mcp
npm install
npm run build
node dist/index.js

🛠️ Ferramentas Disponíveis

Navegação e Interação

puppeteer_navigate - Navegue para URLs com opções de inicialização opcionais
puppeteer_click - Clique em elementos usando seletores CSS
puppeteer_hover - Passe o mouse sobre elementos
puppeteer_fill - Preencha campos de entrada e formulários
puppeteer_select - Selecione opções de menus suspensos

Conteúdo e Automação

puppeteer_screenshot - Capture capturas de tela de página ou elemento
puppeteer_evaluate - Execute JavaScript no contexto do navegador

Recursos

console://logs - Acesse a saída do console do navegador
screenshot://<name> - Recupere capturas de tela capturadas

🔧 Configuração

Configuração do Claude Desktop

Adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
    }
  }
}

Configuração Docker

{
  "mcpServers": {
    "puppeteer": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--init", "-e", "DOCKER_CONTAINER=true", "puppeteer-mcp"]
    }
  }
}

Variáveis de Ambiente

PUPPETEER_LAUNCH_OPTIONS - Opções de inicialização do navegador codificadas em JSON
ALLOW_DANGEROUS - Habilite argumentos perigosos do navegador (padrão: false)
DOCKER_CONTAINER - Sinalizador de detecção de contêiner

Opções de Inicialização do Navegador

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"],
      "env": {
        "PUPPETEER_LAUNCH_OPTIONS": "{\"headless\": false, \"args\": [\"--no-sandbox\"]}",
        "ALLOW_DANGEROUS": "true"
      }
    }
  }
}

🏗️ Desenvolvimento

Desenvolvimento Local

# Clone the repository
git clone https://github.com/code-craka/puppeteer-mcp.git
cd puppeteer-mcp

# Install dependencies
npm install

# Development with watch mode
npm run watch

# Build for production
npm run build

Desenvolvimento Docker

# Build Docker image
docker build -t puppeteer-mcp .

# Run with environment variables
docker run -i --rm --init \
  -e DOCKER_CONTAINER=true \
  -e PUPPETEER_LAUNCH_OPTIONS='{"headless":true}' \
  puppeteer-mcp

☁️ Implantação no Cloudflare Workers

🚀 Implantação de Produção ao Vivo

URL ao Vivo: https://puppeteer.techsci.dev

Nosso servidor Puppeteer MCP está implantado com sucesso no Cloudflare Workers com integração Browserless.io.

✅ Status da Implantação

Status: Ao vivo e operacional
Serviço de Navegador: Browserless.io conectado
Chamadas de API: Screenshots funcionando ✅
Ferramentas Disponíveis: 6 ferramentas de automação de navegador
Tempo de Resposta: média de ~1-2 segundos

🛠️ Implante o Seu Próprio

cd cloudflare-worker
npm install                # Installs Wrangler v4.22.0 + secure dependencies
npx wrangler login
echo "YOUR_BROWSERLESS_TOKEN" | npx wrangler secret put BROWSERLESS_TOKEN
npm run build             # Compile TypeScript to dist/index.js
npm run deploy           # Deploy using latest Wrangler v4.22.0

🧪 Teste a Implantação ao Vivo

# Test tools listing
curl -X POST https://puppeteer.techsci.dev \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":"test"}'

# Test screenshot capture
curl -X POST https://puppeteer.techsci.dev \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"browser_screenshot","arguments":{"name":"test","url":"https://example.com"}},"id":"test"}'

💰 Custos de Produção

Cloudflare Workers: 100.000 solicitações/dia grátis
Browserless.io: ~$0,0025 por segundo de uso do navegador
Estimativa mensal: US$ 10-50 para uso moderado

Consulte README do Cloudflare Worker para instruções detalhadas de configuração.

🔐 Segurança

Medidas de Segurança Padrão

Argumentos perigosos do navegador são filtrados por padrão
Níveis de segurança configuráveis via variáveis de ambiente
Modo headless em contêineres Docker
Permissões com escopo para diferentes ambientes de implantação
Atualizações Recentes: Todas as dependências atualizadas, 0 vulnerabilidades de segurança
Build Seguro: esbuild v0.25.0+ e Wrangler v4.22.0 com os patches mais recentes

Argumentos Perigosos (Filtrados por Padrão)

--no-sandbox
--disable-setuid-sandbox
--single-process
--disable-web-security
--ignore-certificate-errors

Substitua com a variável de ambiente ALLOW_DANGEROUS=true.

📋 Exemplos

Captura de Tela Básica

{
  "name": "puppeteer_screenshot",
  "arguments": {
    "name": "example-page",
    "width": 1280,
    "height": 720
  }
}

Navegar e Interagir

{
  "name": "puppeteer_navigate",
  "arguments": {
    "url": "https://example.com",
    "launchOptions": {
      "headless": false
    }
  }
}

Executar JavaScript

{
  "name": "puppeteer_evaluate",
  "arguments": {
    "script": "return document.title;"
  }
}

📊 Arquitetura

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   MCP Client    │    │  Puppeteer MCP   │    │   Browser       │
│  (Claude, etc.) │◄──►│     Server       │◄──►│  (Chromium)     │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                │
                                ▼
                       ┌──────────────────┐
                       │  Cloud Services  │
                       │ (Browserless.io) │
                       └──────────────────┘

🤝 Contribuindo

Faça um fork do repositório
Crie um branch de recurso: git checkout -b feature/amazing-feature
Faça commit das suas alterações: git commit -m 'Add amazing feature'
Envie para o branch: git push origin feature/amazing-feature
Abra um Pull Request

📄 Licença

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

🙏 Agradecimentos

Model Context Protocol - O protocolo que torna isso possível
Puppeteer - API Node.js do Chrome headless
Anthropic - Implementação original do servidor MCP
Browserless.io - Serviço de automação de navegador em nuvem

🔗 Projetos Relacionados

MCP SDK - SDK do Model Context Protocol
Claude Desktop - Assistente de IA com suporte a MCP
Puppeteer - Biblioteca de automação de navegador

📞 Suporte

Crie uma issue para relatar bugs
Participe das discussões em GitHub Discussions
Consulte o CLAUDE.md para orientações de desenvolvimento

🏷️ Histórico de Versões

v1.0.0 - Lançamento inicial com suporte local ao Puppeteer
v1.1.0 - Adicionado suporte a Docker e compatibilidade com ARM64
v1.2.0 - Adaptação para Cloudflare Workers com serviços de navegador externos
v1.3.0 - ✅ Implantação de Produção ao Vivo - Implantado com sucesso no Cloudflare Workers com integração Browserless.io, testado e confirmado em funcionamento
v1.4.0 - 🔒 Atualização de Segurança e Desempenho - Atualizado Wrangler para v4.22.0, corrigidas vulnerabilidades do esbuild, adicionados logs de observabilidade, resolvidos todos os problemas do npm audit (0 vulnerabilidades)

Autor: Sayem Abdullah Rihan
Licença: MIT
Repositório: github.com/code-craka/puppeteer-mcp