crawlbrulee

o servidor oficial do Model Context Protocol — @crawlbrulee/mcp. permite que agentes compatíveis com mcp (Claude Code, Cursor, Codex, Claude Desktop) façam scraping de páginas, mapeiem sites e verifiquem o uso como chamadas de ferramentas nativas. ele encapsula @crawlbrulee/sdk, fala stdio e é executável com npx. código aberto sob Apache-2.0 — código-fonte no GitHub .

instalação

Claude Code:

claude mcp add crawlbrulee \
  --env CRAWLBRULEE_API_KEY=cwbl_... \
  -- npx -y @crawlbrulee/mcp

Cursor — adicione ao ~/.cursor/mcp.json:

{
  "mcpServers": {
    "crawlbrulee": {
      "command": "npx",
      "args": ["-y", "@crawlbrulee/mcp"],
      "env": { "CRAWLBRULEE_API_KEY": "cwbl_..." }
    }
  }
}

o mesmo padrão funciona para Codex, Claude Desktop e qualquer host mcp com stdio: defina command: npx, args: ["-y", "@crawlbrulee/mcp"] e encaminhe CRAWLBRULEE_API_KEY no bloco env.

como plugin — o plugin crawlbrulee empacota este servidor com as skills do agente e solicita sua chave na instalação. no Claude Code:

/plugin marketplace add crawlbrulee/crawlbrulee-skills
/plugin install crawlbrulee@crawlbrulee

configuração

variável de ambiente	obrigatória	descrição
CRAWLBRULEE_API_KEY	sim	chave de api enviada como Authorization: Bearer ….

a chave é lida na primeira chamada de ferramenta, então um erro de digitação aparece como um erro claro de ferramenta em vez de uma falha na inicialização.

ferramentas

ferramenta	descrição
scrape	busca uma url → markdown, html, links, imagens, screenshot, metadados, elementos.
scrape_async	envia um job de scraping de forma assíncrona; retorna um job_id imediatamente.
scrape_status	verifica o status de um job assíncrono (pending / running / done / failed).
scrape_result	busca o resultado de um job assíncrono concluído (mesmo formato que scrape).
map	enumera as urls de um site (sitemap + descoberta na página).
usage	créditos atuais, cota, concorrência, horário de reset. não aceita argumentos.
whoami	organização + identidade do token por trás da chave configurada.

exemplo de entrada de scrape — apenas url é obrigatório:

{
  "url": "https://example.com",
  "extract": { "markdown": true, "links": true },
  "require_js": false,
  "proxy": "basic"
}

para ler valores nomeados em vez da página inteira, adicione extract.elements à entrada de scrape ou scrape_async. cada chave é um nome, cada valor um seletor css ou um objeto:

{
  "url": "https://books.toscrape.com/",
  "extract": {
    "elements": {
      "heading": "h1",
      "books": {
        "selector": "article.product_pod",
        "all": true,
        "fields": {
          "title": { "selector": "h3 a", "output": "attribute", "attribute": "title" },
          "price": ".price_color"
        }
      }
    }
  }
}

os valores retornam em elements, com os mesmos nomes, sem custo extra. veja elements para os formatos de requisição, regras de seletor e limites.

fluxo assíncrono

use scrape_async em vez de scrape para páginas de longa duração (renderização pesada de js, screenshots de página inteira). ele aceita a mesma entrada que scrape, mais um webhook: { url, metadata } opcional. consulte scrape_status com o job_id retornado até que o status seja done, depois chame scrape_result para buscar a página. se um webhook foi anexado no envio, entregamos um único POST scrape.complete assinado para essa url quando o job termina (com metadata ecoado de volta em data.metadata), para que um agente possa pular completamente o polling.

{ "job_id": "job_abc123" }

objeto de uso

as respostas de scrape, scrape_result e map (e scrape_status quando um job está done) carregam um bloco response_meta.usage de nível superior, para que um agente possa relatar o que foi entregue e quanto custou a chamada. toda operação inclui { total_credit_cost, engine_credit_cost, proxy_multiplier, engine, proxy }; operações de scraping também incluem screenshot_slicing_credit_cost. map não inclui, e restringe engine a http | cache.

falhas de ferramenta retornam um resultado de erro mcp: [<errorName>] <message>, com (HTTP <status>) anexado apenas quando um status http se aplica. se CRAWLBRULEE_API_KEY não estiver definido no host, as chamadas falham com um erro missing_api_key sintético (em vez de uma falha na inicialização) — os agentes podem ramificar pelo código de erro de qualquer forma.