Browserless

Raspagem e automação de qualquer site

Documentação

Browserless MCP Server

Servidor MCP (Model Context Protocol) para Browserless.io — expõe a API de scraper inteligente do Browserless a clientes LLM como Claude Desktop, Cursor, VS Code e Windsurf.

Início Rápido

Obtenha um token de API em browserless.io (há plano gratuito disponível) e aponte seu cliente MCP para o servidor hospedado:

{
  "mcpServers": {
    "browserless": {
      "url": "https://mcp.browserless.io/mcp?token=your-token-here"
    }
  }
}

Sem instalação local — consulte Configuração para trechos por cliente.

Ferramentas

Ferramenta	Descrição
`browserless_smartscraper`	Extrai uma única página web e retorna seu conteúdo como markdown ou HTML. Lida automaticamente com páginas com muito JavaScript e medidas anti-bot. Para conteúdo em várias páginas, use `browserless_crawl`; para listar as URLs de um site, use `browserless_map`.
`browserless_search`	Pesquisa na web usando o Browserless e, opcionalmente, extrai cada resultado. Suporta pesquisa web, de notícias e de imagens com segmentação geográfica e filtros de tempo.
`browserless_map`	Descobre e mapeia todas as URLs de um site. Varre via sitemaps e extração de links. Retorna URLs com títulos e descrições opcionais. Útil para auditorias de sites e descoberta de conteúdo.
`browserless_crawl`	Rastreia um site e extrai todas as páginas descobertas. Suporta controle de profundidade, filtragem de caminhos, estratégias de sitemap e opções de extração configuráveis. Retorna o conteúdo extraído e metadados de cada página.
`browserless_performance`	Executa auditorias Lighthouse em qualquer URL. Retorna pontuações e métricas de acessibilidade, boas práticas, desempenho, PWA e SEO. Opcionalmente, filtra por categoria ou fornece orçamentos de desempenho.
`browserless_function`	Executa JavaScript Puppeteer personalizado na nuvem do Browserless. A função recebe um objeto `page` e um `context` opcional; retorne `{ data, type }` para controlar o payload e o Content-Type.
`browserless_export`	Exporta uma página web via API `/export` do Browserless. Busca a URL e retorna seu conteúdo nativo (HTML, PDF, imagem, etc.) com detecção automática de tipo de conteúdo.
`browserless_agent`	Conduz uma sessão de navegador persistente via loop ReAct: captura a página, planeja, executa interações em lote (clique, digitação, rolagem, avaliação, etc.) e recaptura. Usa seletores baseados em refs derivados das capturas, suporta fluxos de várias abas, capturas de tela, resolução de captchas, URLs ao vivo e upload/download de arquivos (downloads capturados aparecem automaticamente como handles; bytes nunca entram no contexto).
`browserless_skill`	Carrega uma receita sob demanda para mecânicas de página não triviais (shadow DOM, consentimento de cookies, modais, captchas, conteúdo dinâmico, capturas que não encontram o elemento, capturas de tela, abas). Complementar ao `browserless_agent`.

Skills

O servidor vem com uma biblioteca integrada de Skills — receitas sob demanda que o agente pode carregar para lidar com mecânicas de página complicadas. As Skills são injetadas automaticamente nas respostas do browserless_agent quando seus gatilhos disparam (por exemplo, quando o agente encontra um banner de cookies) e também podem ser carregadas manualmente via ferramenta browserless_skill.

Skill	Fonte	Propósito
`shadow-dom`	src/skills/shadow-dom.md	Seletores profundos e segmentação de iframes através de shadow roots.
`cookie-consent`	src/skills/cookie-consent.md	Receitas de dispensa específicas por fornecedor (OneTrust, Cookiebot, Didomi, TrustArc, etc.).
`modals`	src/skills/modals.md	Fechar diálogos, alertas e heurísticas de botão de fechar sobreposições.
`captchas`	src/skills/captchas.md	Uso do comando `solve`, semântica de resposta e caminhos de escalonamento (somente Cloud).
`dynamic-content`	src/skills/dynamic-content.md	Escolher o método `wait*` certo para conteúdo assíncrono/AJAX/SPA.
`snapshot-misses`	src/skills/snapshot-misses.md	Lidar com capturas truncadas/vazias e conteúdo renderizado como imagem.
`screenshots`	src/skills/screenshots.md	Quando capturar tela vs. capturar snapshot, escolhas de escopo e formato.
`tabs`	src/skills/tabs.md	Fluxos de várias abas e visualização sem alternância via `targetId`.

Carregue uma skill explicitamente:

{
  "method": "tools/call",
  "params": {
    "name": "browserless_skill",
    "arguments": { "id": "cookie-consent" },
  },
}

Proxy residencial (`browserless_agent`)

Passe um objeto proxy de nível superior em browserless_agent para rotear a sessão por IPs residenciais. Use isso quando os alvos bloquearem tráfego de datacenter por IP.

{
  "method": "tools/call",
  "params": {
    "name": "browserless_agent",
    "arguments": {
      "method": "goto",
      "params": { "url": "https://example.com" },
      "proxy": {
        "proxy": "residential",
        "proxyCountry": "us",
        "proxySticky": true,
      },
    },
  },
}

Campo	Observações
`proxy`	`"residential"` — único valor suportado hoje.
`proxyCountry`	Código de país ISO-2 (`"us"`, `"de"`). Normalizado automaticamente para minúsculas. Valores não alfabéticos são rejeitados.
`proxyState`	Nome de estado dos EUA com espaços substituídos por underscores (`"new_york"`). Restrito a planos pagos — tokens não elegíveis recebem 401.
`proxyCity`	Cidade alvo. Restrito a planos pagos/enterprise — tokens não elegíveis recebem 401.
`proxySticky`	IP estável enquanto o WebSocket subjacente permanecer aberto. Reconexões (queda por inatividade, oscilação de rede, falha do navegador) alocam um novo ID sticky e um novo IP.
`proxyLocaleMatch`	Corresponder o locale de `navigator` ao país do IP do proxy.
`proxyPreset`	Predefinição nomeada (por exemplo, `"px_amazon01"`). As predefinições disponíveis dependem do plano — pergunte ao suporte do Browserless pela sua lista.
`externalProxyServer`	Proxy upstream próprio, por exemplo, `http://user:pass@host:port`. Deve ser `http://` ou `https://`.

Observação: proxyCountry / proxyState / proxyCity / proxySticky / proxyLocaleMatch / proxyPreset exigem que proxy: "residential" ou externalProxyServer esteja definido. O MCP rejeita essa combinação no momento da validação; sem isso, a API os ignoraria silenciosamente.

O objeto proxy é lido uma única vez na criação da sessão. Para alterá-lo, chame close e inicie uma nova sessão — o cliente agente chaveia as sessões pela impressão digital do proxy, então passar uma configuração diferente cairá em um WebSocket novo.

Configuração

O servidor está hospedado em https://mcp.browserless.io/mcp. Autentique via cabeçalhos (preferido) ou parâmetro de consulta ?token=.

Instalando via agente de IA? Consulte install.md para instruções de configuração legíveis por agentes.

Usando cabeçalhos (recomendado para clientes que os suportam):

{
  "mcpServers": {
    "browserless": {
      "url": "https://mcp.browserless.io/mcp",
      "headers": {
        "Authorization": "Bearer your-token-here"
      }
    }
  }
}

Usando parâmetros de consulta de URL (para clientes como conectores personalizados do Claude.ai que aceitam apenas uma URL):

https://mcp.browserless.io/mcp?token=your-token-here

Para conectar a um endpoint regional específico do Browserless, adicione o cabeçalho x-browserless-api-url ou o parâmetro de consulta browserlessUrl:

{
  "mcpServers": {
    "browserless": {
      "url": "https://mcp.browserless.io/mcp",
      "headers": {
        "Authorization": "Bearer your-token-here",
        "x-browserless-api-url": "https://production-lon.browserless.io"
      }
    }
  }
}

https://mcp.browserless.io/mcp?token=your-token-here&browserlessUrl=https://production-lon.browserless.io

Quando cabeçalhos e parâmetros de consulta estão presentes, os cabeçalhos têm precedência.

Claude Desktop

Adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "browserless": {
      "url": "https://mcp.browserless.io/mcp?token=your-token-here"
    }
  }
}

Cursor

Adicione às configurações de MCP do seu Cursor:

{
  "mcpServers": {
    "browserless": {
      "url": "https://mcp.browserless.io/mcp?token=your-token-here"
    }
  }
}

VS Code

Adicione às configurações do seu VS Code (settings.json):

{
  "mcp": {
    "servers": {
      "browserless": {
        "url": "https://mcp.browserless.io/mcp",
        "headers": {
          "Authorization": "Bearer your-token-here"
        }
      }
    }
  }
}

Windsurf

Adicione à configuração de MCP do seu Windsurf:

{
  "mcpServers": {
    "browserless": {
      "url": "https://mcp.browserless.io/mcp?token=your-token-here"
    }
  }
}

Auto-hospedagem

O servidor também pode ser executado localmente — útil para implantações isoladas ou para apontar para uma instância do Browserless auto-hospedada. Clone este repositório e construa a imagem Docker:

docker build -f docker/Dockerfile -t browserless-mcp .

docker run \
  -e BROWSERLESS_TOKEN=your-token \
  -e BROWSERLESS_API_URL=https://your-browserless-instance.example.com \
  -p 8080:8080 \
  browserless-mcp

Em seguida, aponte seu cliente MCP para http://localhost:8080/mcp usando a mesma autenticação por cabeçalho/parâmetro de consulta acima.

Variáveis de ambiente auto-hospedadas

Variável	Obrigatório	Padrão	Descrição
`BROWSERLESS_TOKEN`	Sim	—	Seu token da API do Browserless
`BROWSERLESS_API_URL`	Não	`https://production-sfo.browserless.io`	Endpoint da API (para Browserless auto-hospedado)
`TRANSPORT`	Não	`stdio`	Tipo de transporte: `stdio` ou `httpStream`
`PORT`	Não	`8080`	Porta do servidor HTTP (somente para transporte `httpStream`)
`BROWSERLESS_TIMEOUT`	Não	`30000`	Tempo limite de requisição em milissegundos
`BROWSERLESS_MAX_RETRIES`	Não	`3`	Máximo de tentativas de repetição para requisições falhas
`BROWSERLESS_CACHE_TTL`	Não	`60000`	TTL de cache em milissegundos (0 para desativar)
`AMPLITUDE_API_KEY`	Não	—	Chave de API do projeto Amplitude. Envia análises de uso do MCP — eventos do ciclo de vida do SDK mais nossos próprios eventos de ferramentas/habilidades
`MCP_COMPLIANCE_MODE`	Não	não definido (superfície completa)	Serve a superfície reduzida e compatível com o diretório. Falha fechada: qualquer valor definido, exceto `false`/`0`/`no`/`off`, ativa isso

Recursos do MCP

URI do Recurso	Descrição
`browserless://api-docs`	Documentação da API do Smart scraper
`browserless://status`	Status de saúde do serviço ao vivo

Prompts do MCP

Prompt	Descrição
`scrape-url`	Extraia uma página da web e resuma seu conteúdo
`extract-content`	Extraia informações específicas de uma página da web

Desenvolvimento

npm install
npm run build
npm test
npm run coverage

Testes

A suíte de testes usa Mocha com Chai e Sinon. As especificações ficam ao lado do código em test/ (test/lib/, test/tools/, test/prompts/, test/resources/, test/integration/) e são executadas contra a saída compilada em build/.

npm test — compila TypeScript e executa cada *.spec.js em build/test/. Nenhum serviço externo ou BROWSERLESS_TOKEN é necessário; o cliente da API é simulado.
npm run coverage — executa a suíte sob c8 com os limiares configurados em package.json (linhas ≥ 80%, ramos ≥ 70%, funções ≥ 80%).

Os testes são executados automaticamente em cada pull request por meio do Workflow de Teste no Node 24. Os PRs devem manter a suíte verde antes de serem mesclados.

Token de API

Obtenha seu token de API em browserless.io. O token autentica todas as solicitações à API do Browserless.

Licença

SSPL-1.0