Browserless

Extrae y automatiza cualquier sitio

Documentación

Servidor MCP de Browserless

Servidor MCP (Model Context Protocol) para Browserless.io — expone la API de scraper inteligente de Browserless a clientes LLM como Claude Desktop, Cursor, VS Code y Windsurf.

Inicio rápido

Obtén un token de API en browserless.io (hay plan gratuito disponible) y luego apunta tu cliente MCP al servidor alojado:

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

Sin instalación local — consulta Configuración para fragmentos por cliente.

Herramientas

Herramienta	Descripción
`browserless_smartscraper`	Extrae una sola página web y devuelve su contenido como markdown o HTML. Maneja páginas con mucho JavaScript y medidas anti-bot automáticamente. Para contenido en múltiples páginas, usa `browserless_crawl`; para listar las URLs de un sitio, usa `browserless_map`.
`browserless_search`	Busca en la web usando Browserless y opcionalmente extrae cada resultado. Admite búsqueda web, de noticias e imágenes con segmentación geográfica y filtros de tiempo.
`browserless_map`	Descubre y mapea todas las URLs de un sitio web. Escanea mediante sitemaps y extracción de enlaces. Devuelve URLs con títulos y descripciones opcionales. Útil para auditorías de sitios y descubrimiento de contenido.
`browserless_crawl`	Rastrea un sitio web y extrae cada página descubierta. Admite control de profundidad, filtrado por rutas, estrategias de sitemap y opciones de extracción configurables. Devuelve contenido extraído y metadatos de cada página.
`browserless_performance`	Ejecuta auditorías de Lighthouse en cualquier URL. Devuelve puntuaciones y métricas de accesibilidad, mejores prácticas, rendimiento, PWA y SEO. Opcionalmente filtra por categoría o proporciona presupuestos de rendimiento.
`browserless_function`	Ejecuta JavaScript personalizado de Puppeteer en la nube de Browserless. La función recibe un objeto `page` y `context` opcional; devuelve `{ data, type }` para controlar el payload y el Content-Type.
`browserless_export`	Exporta una página web mediante la API `/export` de Browserless. Obtiene la URL y devuelve su contenido nativo (HTML, PDF, imagen, etc.) con detección automática de tipo de contenido.
`browserless_agent`	Conduce una sesión de navegador persistente mediante un bucle ReAct: captura la página, planifica, ejecuta interacciones por lotes (clic, escribir, desplazar, evaluar, etc.) y vuelve a capturar. Usa selectores basados en referencias derivados de las capturas, admite flujos de múltiples pestañas, capturas de pantalla, resolución de captchas, URLs en vivo y carga/descarga de archivos (las descargas capturadas aparecen automáticamente como manejadores; los bytes nunca entran en el contexto).
`browserless_skill`	Carga una receta bajo demanda para mecánicas de página no triviales (shadow DOM, consentimiento de cookies, modales, captchas, contenido dinámico, capturas fallidas, capturas de pantalla, pestañas). Complemento de `browserless_agent`.
`browserless_profiles`	Lista los perfiles de autenticación guardados para el token actual, con conteos de cookies y orígenes. Pasa el nombre de un perfil como `profile` a otra herramienta para reutilizar su estado de sesión iniciada.
`browserless_account`	Lee la cuenta detrás del token actual: plan, saldo de unidades, período de facturación y nombres de claves API. Nunca devuelve valores de tokens API.
`browserless_usage`	Lee el consumo de solicitudes y unidades: éxitos, errores, tiempos de espera, colas, concurrencia máxima, captchas, bytes y unidades de proxy. Opcionalmente limitado a claves API específicas.
`browserless_sessions`	Inspecciona las sesiones de la cuenta — navegadores ejecutándose ahora, sesiones persistentes en trabajadores dedicados, reproducciones de sesiones grabadas e integraciones de credenciales de 1Password. También descarga una reproducción como página de reproductor rrweb completamente autocontenida (`action: "replay"`) que no necesita red para renderizarse: se abre en tu navegador cuando el servidor se ejecuta localmente; de lo contrario, se adjunta como recurso HTML en línea cuando es lo suficientemente pequeño para enviar.
`browserless_logs`	Lee el registro propio de Browserless de solicitudes recientes: qué se intentó, si falló, por qué se detuvo, cuánto tardó y cuánto costó. La herramienta para diagnosticar una ejecución que falló en el lado de Browserless. La ventana disponible depende del plan.

Habilidades

El servidor incluye una biblioteca integrada de Habilidades — recetas bajo demanda que el agente puede cargar para manejar mecánicas de página complicadas. Las habilidades se inyectan automáticamente en las respuestas de browserless_agent cuando se activan sus disparadores (por ejemplo, el agente encuentra un banner de cookies), y también se pueden cargar manualmente mediante la herramienta browserless_skill.

Habilidad	Fuente	Propósito
`shadow-dom`	src/skills/shadow-dom.md	Selectores profundos y direccionamiento de iframes a través de raíces shadow.
`cookie-consent`	src/skills/cookie-consent.md	Recetas de descarte específicas por proveedor (OneTrust, Cookiebot, Didomi, TrustArc, etc.).
`modals`	src/skills/modals.md	Cierre de diálogos, diálogos de alerta y heurísticas de botones de cierre de superposiciones.
`captchas`	src/skills/captchas.md	Uso del comando `solve`, semántica de respuesta y rutas de escalamiento (solo Cloud).
`dynamic-content`	src/skills/dynamic-content.md	Elección del método `wait*` correcto para contenido asíncrono/AJAX/SPA.
`snapshot-misses`	src/skills/snapshot-misses.md	Manejo de capturas truncadas/vacías y contenido renderizado como imagen.
`screenshots`	src/skills/screenshots.md	Cuándo usar captura de pantalla vs. captura, opciones de alcance y formato.
`tabs`	src/skills/tabs.md	Flujos de múltiples pestañas y vista previa sin cambiar mediante `targetId`.

Carga una habilidad explícitamente:

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

Proxy integrado (`browserless_agent`)

Pasa un objeto proxy de nivel superior en browserless_agent para enrutar la sesión a través de IPs de centro de datos o residenciales. El centro de datos es más barato por MB; el residencial tiene menos probabilidades 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 costo o `"residential"` cuando los objetivos bloquean tráfico de centro de datos.
`proxyCountry`	Código de país ISO-2 (`"us"`, `"de"`). Normalizado automáticamente a minúsculas. Los valores no alfabéticos se rechazan.
`proxyState`	Nombre de estado de EE. UU. con espacios reemplazados por guiones bajos (`"new_york"`). Restringido a planes de pago — los tokens no elegibles reciben un 401.
`proxyCity`	Objetivo de ciudad. Restringido a planes de pago/empresa — los tokens no elegibles reciben un 401.
`proxySticky`	IP estable mientras el WebSocket subyacente permanezca abierto. Las reconexiones (caída por inactividad, fallo de red, cierre del navegador) asignan un nuevo id fijo y una nueva IP.
`proxyLocaleMatch`	Coincide la configuración regional de `navigator` con el país de la IP del proxy.
`proxyPreset`	Preajuste nombrado solo residencial (por ejemplo, `"px_amazon01"`). Los preajustes disponibles dependen del plan — consulta al soporte de Browserless para tu lista.
`externalProxyServer`	Proxy ascendente propio, por ejemplo, `http://user:pass@host:port`. Debe ser `http://` o `https://`.

Nota: Las opciones geográficas, fijas y de configuración regional requieren un nivel proxy integrado o externalProxyServer; proxyPreset requiere proxy: "residential". El MCP rechaza combinaciones no compatibles en lugar de permitir que la API las ignore silenciosamente. El objeto proxy se lee una vez al crear la sesión. Para cambiarlo, llama a close e inicia una nueva sesión: el cliente del agente vincula las sesiones al fingerprint del proxy, por lo que pasar una configuración diferente aterrizará en un WebSocket nuevo.

Persona del sistema operativo (`browserless_agent`)

Las sesiones del agente pueden optar por una persona de sistema operativo coherente con opciones de creación de nivel superior:

Campo	Notas
`emulationOs`	`"windows"`, `"macos"`, `"linux"` o `"android"`. Habilita la suplantación de plataforma.
`emulatedDevice`	Slug de dispositivo Android; se usa solo con `emulationOs: "android"`.
`screen`	Pantalla de escritorio en formato `WIDTHxHEIGHT`.
`deviceScaleFactor`	Relación de píxeles del dispositivo de escritorio: `1` o `1.25`.
`deviceSlot`	Ranura de dispositivo de escritorio estable no negativa; el servidor valida el rango específico de la cuenta.

Configura las opciones de persona en la primera llamada antes de la navegación y reutiliza el sessionId devuelto después. La persona es fija durante la vida de esa sesión de navegador; ciérrala antes de seleccionar una persona diferente.

Configuración

El servidor está alojado en https://mcp.browserless.io/mcp. Autentícate mediante encabezados (preferido) o un parámetro de consulta ?token=.

¿Instalando mediante un agente de IA? Consulta install.md para instrucciones de configuración legibles por agentes.

Usando encabezados (recomendado para clientes que los admitan):

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

Usando parámetros de consulta URL (para clientes como conectores personalizados de Claude.ai que solo aceptan una URL):

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

Para conectarte a un endpoint regional específico de Browserless, agrega el encabezado x-browserless-api-url o el 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

Cuando tanto los encabezados como los parámetros de consulta están presentes, los encabezados tienen prioridad.

Las anulaciones de URL de API se limitan a browserless.io, sus subdominios, el origen BROWSERLESS_API_URL configurado (mismo esquema, nombre de host y puerto) y los hosts listados en MCP_ALLOWED_API_URL_HOSTS. Las rutas están permitidas, pero las credenciales, cadenas de consulta y fragmentos (incluidos ? o # desnudos) no lo están. Sin una anulación, la URL configurada por el operador se usa sin cambios.

Claude Desktop

Agrega a tu claude_desktop_config.json:

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

Cursor

Agrega a tu configuración de MCP de Cursor:

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

VS Code

Agrega a tu configuración de VS Code (settings.json):

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

Windsurf

Agrega a tu configuración de MCP de Windsurf:

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

Autoalojamiento

El servidor también se puede ejecutar localmente, útil para implementaciones aisladas o para apuntar a una instancia de Browserless autoalojada. Clona este repositorio y construye la imagen 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

Luego apunta tu cliente MCP a http://localhost:8080/mcp usando la misma autenticación de encabezado/parámetro de consulta que arriba.

Variables de entorno autoalojadas

Variable	Requerida	Predeterminado	Descripción
`BROWSERLESS_TOKEN`	Sí	—	Tu token de API de Browserless
`BROWSERLESS_API_URL`	No	`https://production-sfo.browserless.io`	Endpoint de API (para Browserless autoalojado)
`MCP_ALLOWED_API_URL_HOSTS`	No	—	Hosts separados por comas permitidos para anulaciones de URL de API proporcionadas por el cliente, además de Browserless y el origen de API configurado
`BROWSERLESS_API_SERVER`	No	`https://api.browserless.io`	Host de API de cuenta: respalda `browserless_account`, `_usage`, `_sessions` y `_logs`. Un host diferente de `BROWSERLESS_API_URL`, que es un tiempo de ejecución de navegador
`BROWSERLESS_REPLAY_CDN_URL`	No	`https://d3uycvholi7jx8.cloudfront.net/`	Origen que sirve artefactos de reproducción de sesión. Las rutas de reproducción se verifican contra su origen
`TRANSPORT`	No	`stdio`	Tipo de transporte: `stdio` o `httpStream`
`PORT`	No	`8080`	Puerto del servidor HTTP (solo para transporte `httpStream`)
`BROWSERLESS_TIMEOUT`	No	`30000`	Tiempo de espera de solicitud en milisegundos
`BROWSERLESS_MAX_RETRIES`	No	`3`	Máximo de intentos de reintento para solicitudes fallidas
`BROWSERLESS_CACHE_TTL`	No	`60000`	TTL de caché en milisegundos (0 para deshabilitar)
`AMPLITUDE_API_KEY`	No	—	Clave de API del proyecto Amplitude. Envía análisis de uso de MCP: eventos del ciclo de vida del SDK más nuestros propios eventos de herramientas/habilidades
`MCP_COMPLIANCE_MODE`	No	sin configurar (superficie completa)	Sirve la superficie reducida y conforme al directorio. Falla de forma cerrada: cualquier valor configurado excepto `false`/`0`/`no`/`off` lo habilita

Diagnósticos de recuperación de habilidades

Skill Retrieval Completed se emite una vez por cada recuperación remota real de habilidades a través de la cola de análisis existente (cuando ANALYTICS_ENABLED, SQS_QUEUE_URL y SQS_REGION están configurados). No se duplica a través del transporte AMPLITUDE_API_KEY del SDK. Los aciertos de caché y los llamadores concurrentes que comparten una recuperación no emiten otra finalización. Las recuperaciones fallidas siguen siendo reintentables en la siguiente llamada; esta instrumentación no agrega reintentos.

Los campos son result=hit|miss|error, domain normalizado, UUID request_id, source, attempt, duration_ms entero, stage=fetch|decode|validate y http_status disponible. skill_count aparece solo en respuestas válidas: positivo para aciertos, cero para fallos. Los errores llevan error_category=timeout|network_error|http_error|invalid_json|invalid_shape. Las fuentes son cli_agent, script_builder, autologin, agent_run, mcp_client, o unknown. Cada recuperación actualmente tiene attempt=1; no hay identificador de ejecución disponible en estos sitios de llamada, por lo que run_id se omite. Los dominios fuera del formato de nombre de host acotado se convierten en invalid sin eliminar la finalización del denominador.

Configura OTEL_EXPORTER_OTLP_LOGS_ENDPOINT a la URL completa de /v1/logs de un recolector confiable para exportar registros WARN de skill.retrieval.failed coincidentes como JSON OTLP/HTTP. El valor predeterminado está deshabilitado. Las exportaciones tienen un plazo de un segundo, como máximo 16 solicitudes en vuelo y sin reintento. Los errores de análisis de cola/habilidades capturados producen skill.telemetry.delivery_failed con originating_event y la categoría de diagnóstico fija delivery_error, como máximo una vez por minuto por proceso. Los fallos del exportador se tragan sin informarse recursivamente. Ningún registro nuevo contiene tokens, indicaciones, URL completas, cuerpos de respuesta o texto de recetas. La cola conserva su campo de autenticación existente, separado de los campos de registro.

Ejemplo de atributos de fallo:

{
  "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
}

La tasa de error de recuperación es finalizaciones de error / todas las finalizaciones. La tasa de aciertos es finalizaciones de aciertos / finalizaciones válidas. No agregues los eventos separados del servidor Skill Lookup a ninguno de los denominadores. Las pruebas usan sumideros locales/simulados; un exportador configurado o un mensaje de consola no es prueba de recepción remota.

Diagnósticos de fallos

MCP Tool Request conserva analytics_version=2, el error_category grueso existente, status_code, propiedades de tiempo y específicas de la herramienta. Estos campos de diagnóstico aditivos son solo de fallo; un reintento exitoso no tiene ninguno de ellos.

Propiedad	Significado
`error_reason`	`selector_miss`, `invalid_params`, `unknown_method`, `script_error`, `unauthorized`, `forbidden`, `not_found`, `server_error`, `session_lost`, `navigation_failed`, `timeout` o `unknown`. Los errores de agente conservan su clasificación detallada existente; la validación de URL local/lote es `invalid_params`.
`error_source`	`validation`, `script`, `target_website`, `api`, `transport` o `unknown`. Esto identifica el límite de fallo observado, no la culpa. Un 403 por sí solo no identifica su origen.
`failed_command_index`	Índice basado en cero en el lote de comandos de la invocación, no el contador de comandos de toda la sesión. Se omite cuando la configuración/validación falla antes de que comience un comando.
`failed_method`	El nombre del método tipado reconocido del comando fallido. Los nombres de métodos de forma libre no reconocidos se omiten para evitar emitir entrada arbitraria; el índice aún identifica el comando.
`error_code`	Códigos estructurados en lista permitida: los nombres de razones en mayúsculas anteriores, `SELECTOR_NOT_FOUND`, `BROWSER_CRASHED`, `ECONNRESET`, `ECONNREFUSED`, `ENOTFOUND`, `EAI_AGAIN`, `ETIMEDOUT`. Los códigos opacos/no reconocidos se omiten, no se copian en los mensajes.
`error_status_code`	Un estado HTTP entero (100–599) transportado por metadatos de error estructurados. Nunca se extrae de la prosa del error.
`error_status_origin`	`api` para una respuesta/actualización de API observada, `target_website` para un resultado de navegación fallido, de lo contrario `unknown`. Se omite cuando no hay un estado estructurado disponible.
`error_message`	Un resumen sintetizado limitado a 500 caracteres. Los mensajes de error crudos, cuerpos de respuesta, HTML, scripts, selectores, credenciales, cookies, cabeceras de autorización y URLs nunca se copian en este campo.

status_code conserva su significado original específico de la herramienta; los nuevos campos de estado no lo reemplazan ni convierten respuestas HTTP exitosas de la página objetivo en fallos. Los fallos HTTP conservan el estado de respuesta de la API incluso cuando se lanzan. Los códigos se conservan cuando ya están disponibles en errores estructurados o en el cuerpo JSON leído por el manejador de errores 4xx existente; los diagnósticos no leen cuerpos adicionales en fallos 5xx.

Una búsqueda sin éxito sin evidencia estructurada reporta error_reason=unknown y error_message="Unclassified search failure.". Su categoría heredada user_error permanece para compatibilidad de gráficos, no como evidencia de culpa del llamador.

Ejemplos de desglose: filtrar por success=false y agrupar por tool → error_reason; para llamadas de agente, agrupar por failed_method → error_reason; para fallos HTTP, agrupar por error_status_origin → error_status_code. Los campos faltantes en eventos más antiguos significan instrumentación no disponible, no un fallo de unknown. No hay relleno histórico. Verifique los eventos representativos recibidos después del despliegue antes de tratar estas propiedades como disponibles en producción.

Recursos MCP

URI del recurso	Descripción
`browserless://api-docs`	Documentación de la API de Smart scraper
`browserless://status`	Estado de salud del servicio en vivo

Prompts MCP

Prompt	Descripción
`scrape-url`	Extraer una página web y resumir su contenido
`extract-content`	Extraer información específica de una página web

Desarrollo

npm install
npm run build
npm test
npm run coverage

Pruebas

La suite de pruebas usa Mocha con Chai y Sinon. Las especificaciones viven junto al código en test/ (test/lib/, test/tools/, test/prompts/, test/resources/, test/integration/) y se ejecutan contra la salida compilada en build/.

npm test — compila TypeScript y ejecuta cada *.spec.js bajo build/test/. No se requieren servicios externos ni BROWSERLESS_TOKEN; el cliente de la API está simulado.
npm run coverage — ejecuta la suite bajo c8 con los umbrales configurados en package.json (líneas ≥ 80%, ramas ≥ 70%, funciones ≥ 80%).

Las pruebas se ejecutan automáticamente en cada pull request mediante el flujo de trabajo de Test en Node 24. Los PR deben mantener la suite en verde antes de poder fusionarse.

Token de API

Obtén tu token de API en browserless.io. El token autentica todas las solicitudes a la API de Browserless.

Licencia

SSPL-1.0