Browserless

Raspagem e automação de qualquer site

Documentação

Servidor MCP Browserless

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

Início Rápido

Obtenha um token de API em browserless.io (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 — veja Configuração para trechos por cliente.

Ferramentas

Ferramenta	Descrição
`browserless_smartscraper`	Raspe uma única página web e retorne 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`	Pesquise na web usando o Browserless e opcionalmente raspe cada resultado. Suporta pesquisa web, de notícias e de imagens com segmentação geográfica e filtros de tempo.
`browserless_map`	Descubra e mapeie todas as URLs de um site. Escaneia 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`	Rastreie um site e raspe cada página descoberta. Suporta controle de profundidade, filtragem de caminhos, estratégias de sitemap e opções de raspagem configuráveis. Retorna conteúdo raspado e metadados para cada página.
`browserless_performance`	Execute auditorias Lighthouse em qualquer URL. Retorna pontuações e métricas para acessibilidade, boas práticas, desempenho, PWA e SEO. Opcionalmente, filtre por categoria ou forneça orçamentos de desempenho.
`browserless_function`	Execute JavaScript Puppeteer personalizado na nuvem do Browserless. A função recebe um objeto `page` e `context` opcional; retorne `{ data, type }` para controlar o payload e o Content-Type.
`browserless_export`	Exporte uma página web via a 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`	Conduza uma sessão de navegador persistente via um loop ReAct: tire um snapshot da página, planeje, execute interações em lote (clique, digite, role, avalie, etc.) e tire outro snapshot. Usa seletores baseados em refs derivados de snapshots, suporta fluxos de múltiplas 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`	Carregue uma receita sob demanda para um mecanismo de página não trivial (shadow DOM, consentimento de cookies, modais, captchas, conteúdo dinâmico, falhas de snapshot, capturas de tela, abas). Complemento de `browserless_agent`.
`browserless_profiles`	Liste os perfis de autenticação salvos para o token atual, com contagens de cookies e origens. Passe o nome de um perfil como `profile` para outra ferramenta para reutilizar seu estado de login.
`browserless_account`	Leia a conta por trás do token atual: plano, saldo de unidades, período de cobrança e nomes de chaves de API. Nunca retorna valores de tokens de API.
`browserless_usage`	Leia o consumo de requisições e unidades: sucessos, erros, timeouts, fila, concorrência máxima, captchas, bytes e unidades de proxy. Opcionalmente, escopo para chaves de API específicas.
`browserless_sessions`	Inspecione as sessões da conta — navegadores em execução agora, sessões persistentes em workers dedicados, replays de sessões gravadas e integrações de credenciais 1Password. Também baixa um replay como uma página de player rrweb totalmente autocontida (`action: "replay"`) que não precisa de rede para renderizar: aberta no seu navegador quando o servidor roda localmente, caso contrário anexada como um recurso HTML inline quando pequena o suficiente para enviar.
`browserless_logs`	Leia o registro próprio do Browserless de requisições recentes: o que foi tentado, se falhou, por que parou, quanto tempo levou e quanto custou. A ferramenta para diagnosticar uma execução que falhou no lado do Browserless. A janela disponível depende do plano.

Skills

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

Skill	Fonte	Propósito
`shadow-dom`	src/skills/shadow-dom.md	Seletores profundos e direcionamento 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, diálogos de alerta e heurísticas de botões de fechar sobreposições.
`captchas`	src/skills/captchas.md	Usando o comando `solve`, semântica de resposta e caminhos de escalonamento (somente Cloud).
`dynamic-content`	src/skills/dynamic-content.md	Escolhendo o método `wait*` certo para conteúdo assíncrono/AJAX/SPA.
`snapshot-misses`	src/skills/snapshot-misses.md	Lidando com snapshots truncados/vazios e conteúdo renderizado como imagem.
`screenshots`	src/skills/screenshots.md	Quando capturar tela vs. snapshot, opções de escopo e formato.
`tabs`	src/skills/tabs.md	Fluxos de múltiplas abas e espiar sem alternar via `targetId`.

Carregue uma skill explicitamente:

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

Proxy embutido (`browserless_agent`)

Passe um objeto proxy de nível superior em browserless_agent para rotear a sessão através de IPs de datacenter ou residenciais. Datacenter é mais barato por MB; residencial tem menos probabilidade de ser bloqueado.

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

Campo	Notas
`proxy`	`"datacenter"` para menor custo ou `"residential"` quando os alvos bloqueiam tráfego de datacenter.
`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`	Alvo de cidade. Restrito a planos pagos/empresariais — tokens não elegíveis recebem 401.
`proxySticky`	IP estável enquanto o WebSocket subjacente permanecer aberto. Reconexões (queda por inatividade, instabilidade de rede, falha do navegador) alocam um novo id fixo e novo IP.
`proxyLocaleMatch`	Corresponder o locale `navigator` ao país do IP do proxy.
`proxyPreset`	Predefinição nomeada somente residencial (ex.: `"px_amazon01"`). As predefinições disponíveis dependem do plano — pergunte ao suporte do Browserless pela sua lista.
`externalProxyServer`	Traga seu próprio upstream, ex.: `http://user:pass@host:port`. Deve ser `http://` ou `https://`.

Nota: Opções geográficas, fixas e de locale exigem um nível proxy embutido ou externalProxyServer; proxyPreset exige proxy: "residential". O MCP rejeita combinações não suportadas em vez de deixar a API ignorá-las silenciosamente. O objeto proxy é lido uma vez na criação da sessão. Para alterá-lo, chame close e inicie uma nova sessão — o cliente do agente associa sessões à impressão digital do proxy, então passar uma configuração diferente resultará em um novo WebSocket.

Persona de SO (`browserless_agent`)

Sessões de agente podem optar por uma persona de SO coerente com opções de criação de nível superior:

Campo	Notas
`emulationOs`	`"windows"`, `"macos"`, `"linux"` ou `"android"`. Habilita a falsificação de plataforma.
`emulatedDevice`	Slug de dispositivo Android; usado apenas com `emulationOs: "android"`.
`screen`	Tela de desktop no formato `WIDTHxHEIGHT`.
`deviceScaleFactor`	Proporção de pixels do dispositivo desktop: `1` ou `1.25`.
`deviceSlot`	Slot estável não negativo de dispositivo desktop; o servidor valida o intervalo específico da conta.

Defina as opções de persona na primeira chamada antes da navegação e reutilize o sessionId retornado posteriormente. A persona é fixa durante toda a vida daquela sessão de navegador; feche-a antes de selecionar uma persona diferente.

Configuração

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

Instalando por meio de um 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 ambos cabeçalhos e parâmetros de consulta estão presentes, os cabeçalhos têm precedência.

Substituições de URL da API são limitadas a browserless.io, seus subdomínios, a origem BROWSERLESS_API_URL configurada (mesmo esquema, hostname e porta) e hosts listados em MCP_ALLOWED_API_URL_HOSTS. Caminhos são permitidos, mas credenciais, strings de consulta e fragmentos (incluindo ? ou # nus) não são. Sem uma substituição, a URL configurada pelo operador é usada sem alterações.

Claude Desktop

Adicione ao seu claude_desktop_config.json:

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

Cursor

Adicione às suas configurações MCP do Cursor:

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

VS Code

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

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

Windsurf

Adicione à sua configuração MCP do 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 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 de cabeçalho/parâmetro de consulta acima.

Variáveis de ambiente auto-hospedadas

Variável	Obrigatória	Padrão	Descrição
`BROWSERLESS_TOKEN`	Sim	—	Seu token de API do Browserless
`BROWSERLESS_API_URL`	Não	`https://production-sfo.browserless.io`	Endpoint da API (para Browserless auto-hospedado)
`MCP_ALLOWED_API_URL_HOSTS`	Não	—	Hosts separados por vírgula permitidos para substituições de URL da API fornecidas pelo cliente, além do Browserless e da origem da API configurada
`BROWSERLESS_API_SERVER`	Não	`https://api.browserless.io`	Host da API da conta — dá suporte a `browserless_account`, `_usage`, `_sessions` e `_logs`. Um host diferente de `BROWSERLESS_API_URL`, que é um runtime de navegador
`BROWSERLESS_REPLAY_CDN_URL`	Não	`https://d3uycvholi7jx8.cloudfront.net/`	Origem que serve artefatos de replay de sessão. Caminhos de replay são verificados contra ela em relação à origem
`TRANSPORT`	Não	`stdio`	Tipo de transporte: `stdio` ou `httpStream`
`PORT`	Não	`8080`	Porta do servidor HTTP (apenas para transporte `httpStream`)
`BROWSERLESS_TIMEOUT`	Não	`30000`	Tempo limite de solicitação em milissegundos
`BROWSERLESS_MAX_RETRIES`	Não	`3`	Máximo de tentativas de repetição para solicitações com falha
`BROWSERLESS_CACHE_TTL`	Não	`60000`	TTL do cache em milissegundos (0 para desativar)
`AMPLITUDE_API_KEY`	Não	—	Chave da 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/skills
`MCP_COMPLIANCE_MODE`	Não	não definido (superfície completa)	Serve a superfície reduzida e compatível com diretórios. Falha de forma fechada: qualquer valor definido exceto `false`/`0`/`no`/`off` o habilita

Diagnósticos de recuperação de skills

Skill Retrieval Completed é emitido uma vez por busca remota real de skill através da fila de análises existente (quando ANALYTICS_ENABLED, SQS_QUEUE_URL e SQS_REGION estão configurados). Não é duplicado através do transporte AMPLITUDE_API_KEY do SDK. Acertos de cache e chamadores concorrentes compartilhando uma busca não emitem outra conclusão. Recuperações com falha permanecem repetíveis na próxima chamada; esta instrumentação não adiciona repetições.

Os campos são result=hit|miss|error, domain normalizado, UUID request_id, source, attempt, inteiro duration_ms, stage=fetch|decode|validate e http_status disponível. skill_count aparece apenas em respostas válidas: positivo para acertos, zero para erros. Erros carregam error_category=timeout|network_error|http_error|invalid_json|invalid_shape. As fontes são cli_agent, script_builder, autologin, agent_run, mcp_client, ou unknown. Cada busca atualmente tem attempt=1; nenhum identificador de execução está disponível nesses pontos de chamada, então run_id é omitido. Domínios fora do formato de hostname limitado tornam-se invalid sem descartar a conclusão do denominador.

Defina OTEL_EXPORTER_OTLP_LOGS_ENDPOINT para a URL completa /v1/logs de um coletor confiável para exportar registros WARN skill.retrieval.failed correspondentes como JSON OTLP/HTTP. O padrão é desativado. As exportações têm um prazo de um segundo, no máximo 16 solicitações em andamento e sem repetição. Erros de análises de fila/skills capturados produzem skill.telemetry.delivery_failed com originating_event e a categoria de diagnóstico fixa delivery_error, no máximo uma vez por minuto por processo. Falhas do exportador são engolidas sem se reportar recursivamente. Nenhum novo log contém tokens, prompts, URLs completas, corpos de resposta ou texto de receita. A fila mantém seu campo de autenticação existente, separadamente dos campos de log.

Exemplo de atributos de falha:

{
  "event.name": "skill.retrieval.failed",
  "result": "error",
  "domain": "shop.example",
  "request_id": "416e0409-25e2-4399-a3fa-6939f43a75e0",
  "source": "mcp_client",
  "attempt": 1,
  "stage": "fetch",
  "error_category": "http_error",
  "http_status": 429,
  "duration_ms": 17
}

A taxa de erro de recuperação é conclusões de erro / todas as conclusões. A taxa de acertos é conclusões de acerto / conclusões válidas. Não adicione os eventos separados do servidor Skill Lookup a nenhum dos denominadores. Testes usam sumidouros locais/de simulação; um exportador configurado ou mensagem de console não é prova de recebimento remoto.

Diagnósticos de falha

MCP Tool Request retém analytics_version=2, o error_category grosseiro existente, status_code, propriedades de tempo e específicas de ferramenta. Estes campos de diagnóstico aditivos são apenas para falhas; uma repetição bem-sucedida não tem nenhum deles.

Propriedade	Significado
`error_reason`	`selector_miss`, `invalid_params`, `unknown_method`, `script_error`, `unauthorized`, `forbidden`, `not_found`, `server_error`, `session_lost`, `navigation_failed`, `timeout` ou `unknown`. Erros de agente mantêm sua classificação detalhada existente; a validação local de URL/lote é `invalid_params`.
`error_source`	`validation`, `script`, `target_website`, `api`, `transport` ou `unknown`. Isso identifica o limite de falha observado, não a culpa. Um 403 sozinho não identifica sua origem.
`failed_command_index`	Índice baseado em zero no lote de comandos da invocação, não o contador de comandos da sessão. Omitido quando a configuração/validação falha antes de um comando iniciar.
`failed_method`	O nome do método tipado reconhecido do comando que falhou. Nomes de métodos de forma livre não reconhecidos são omitidos para evitar emitir entrada arbitrária; o índice ainda identifica o comando.
`error_code`	Códigos estruturados na lista de permissões: os nomes de razão em maiúsculas acima, `SELECTOR_NOT_FOUND`, `BROWSER_CRASHED`, `ECONNRESET`, `ECONNREFUSED`, `ENOTFOUND`, `EAI_AGAIN`, `ETIMEDOUT`. Códigos opacos/não reconhecidos são omitidos, não copiados nas mensagens.
`error_status_code`	Um status HTTP inteiro (100–599) transportado pelos metadados de erro estruturados. Nunca extraído da prosa do erro.
`error_status_origin`	`api` para uma resposta/atualização de API observada, `target_website` para um resultado de navegação com falha, caso contrário `unknown`. Omitido quando nenhum status estruturado está disponível.
`error_message`	Um resumo sintetizado limitado a 500 caracteres. Mensagens de erro brutas, corpos de resposta, HTML, scripts, seletores, credenciais, cookies, cabeçalhos de autorização e URLs nunca são copiados neste campo.

status_code mantém seu significado original específico da ferramenta; os novos campos de status não o substituem nem transformam respostas HTTP bem-sucedidas de páginas de destino em falhas. Falhas HTTP retêm o status da resposta da API mesmo quando lançadas. Códigos são retidos quando já disponíveis em erros estruturados ou no corpo JSON lido pelo manipulador de erros 4xx existente; diagnósticos não leem corpos adicionais em falhas 5xx.

Uma busca sem sucesso sem evidência estruturada relata error_reason=unknown e error_message="Unclassified search failure.". Sua categoria legada user_error permanece para compatibilidade de gráficos, não como evidência de culpa do chamador.

Exemplos de detalhamento: filtrar por success=false e agrupar por tool → error_reason; para chamadas de agente, agrupar por failed_method → error_reason; para falhas HTTP, agrupar por error_status_origin → error_status_code. Campos ausentes em eventos mais antigos significam instrumentação indisponível, não uma falha de unknown. Não há preenchimento retroativo histórico. Verifique eventos representativos recebidos após a implantação antes de tratar essas propriedades como disponíveis em produção.

Recursos 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 MCP

Prompt	Descrição
`scrape-url`	Raspar uma página da web e resumir seu conteúdo
`extract-content`	Extrair 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 junto ao 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 sob 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 limites configurados em package.json (linhas ≥ 80%, ramos ≥ 70%, funções ≥ 80%).

Os testes são executados automaticamente em cada pull request via fluxo de trabalho de Teste no Node 24. PRs devem manter a suíte verde antes de poderem ser mesclados.

Token da API

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

Licença

SSPL-1.0