crawlbrulee

el servidor oficial de Model Context Protocol — @crawlbrulee/mcp. permite que agentes compatibles con MCP (Claude Code, Cursor, Codex, Claude Desktop) extraigan páginas, mapeen sitios y consulten el uso como llamadas de herramientas nativas. envuelve @crawlbrulee/sdk, habla stdio y es ejecutable con npx. código abierto bajo Apache-2.0 — fuente en GitHub.

instalación

Claude Code:

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

Cursor — añade a ~/.cursor/mcp.json:

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

el mismo patrón funciona para Codex, Claude Desktop y cualquier host stdio de MCP: establece command: npx, args: ["-y", "@crawlbrulee/mcp"] y reenvía CRAWLBRULEE_API_KEY en el bloque de entorno.

como plugin — el plugin crawlbrulee incluye este servidor con las habilidades del agente y solicita tu clave durante la instalación. en Claude Code:

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

configuración

variable de entorno	requerida	descripción
CRAWLBRULEE_API_KEY	sí	clave de API enviada como Authorization: Bearer ….

la clave se lee en la primera llamada a una herramienta, por lo que un error tipográfico aparece como un error claro de herramienta en lugar de un fallo al iniciar.

herramientas

herramienta	descripción
scrape	obtiene una url → markdown, html, enlaces, imágenes, captura de pantalla, metadatos, elementos.
scrape_async	envía un trabajo de extracción de forma asíncrona; devuelve un job_id inmediatamente.
scrape_status	consulta el estado de un trabajo asíncrono (pending / running / done / failed).
scrape_result	obtiene el resultado de un trabajo asíncrono completado (misma forma que scrape).
map	enumera las urls de un sitio (sitemap + descubrimiento en la página).
usage	créditos actuales, cuota, concurrencia, tiempo de reinicio. no acepta argumentos.
whoami	identidad de la organización y del token detrás de la clave configurada.

ejemplo de entrada de scrape — solo se requiere url:

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

para leer valores con nombre en lugar de toda la página, añade extract.elements a la entrada de scrape o scrape_async. cada clave es un nombre, cada valor un selector css o un 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"
        }
      }
    }
  }
}

los valores se devuelven en elements, con los mismos nombres, sin coste adicional. consulta elements para los formatos de solicitud, reglas de selector y límites.

flujo de trabajo asíncrono

usa scrape_async en lugar de scrape para páginas de larga duración (renderizado js pesado, capturas de pantalla de página completa). acepta la misma entrada que scrape, además de un webhook: { url, metadata } opcional. consulta scrape_status con el job_id devuelto hasta que el estado sea done, luego llama a scrape_result para obtener la página. si se adjuntó un webhook al enviar, entregamos un único POST scrape.complete firmado a esa url cuando el trabajo finaliza (con metadata repetido bajo data.metadata), para que un agente pueda omitir la consulta por completo.

{ "job_id": "job_abc123" }

objeto de uso

las respuestas de scrape, scrape_result y map (y scrape_status una vez que un trabajo está done) incluyen un bloque response_meta.usage de nivel superior, para que un agente pueda informar qué se entregó y cuánto costó la llamada. cada operación incluye { total_credit_cost, engine_credit_cost, proxy_multiplier, engine, proxy }; las operaciones de extracción también incluyen screenshot_slicing_credit_cost. map no lo hace y limita engine a http | cache.

los fallos de herramientas devuelven un resultado de error mcp: [<errorName>] <message>, con (HTTP <status>) añadido solo cuando aplica un estado http. si CRAWLBRULEE_API_KEY no está configurado en el host, las llamadas fallan con un error sintético missing_api_key (en lugar de un fallo al iniciar) — los agentes pueden ramificar según el código de error en cualquier caso.