unbrowser by Unchained

unbrowser

El pase de navegador económico para agentes. Un binario nativo. Sin Chrome.

Identidad oficial del Registro MCP: mcp-name: io.github.protostatis/unbrowser

unbrowser es un runtime web sin interfaz visual y con estado para agentes. Se sitúa entre curl/WebFetch y un navegador real: conserva cookies y estado del DOM, devuelve referencias de elementos consultables, maneja enlaces y formularios HTML, detecta señales de desafíos y SPA, y puede ejecutar scripts QuickJS acotados cuando el HTML estático no es suficiente.

El navigate predeterminado es un pase rápido estático/SSR. Configura exec_scripts: true solo cuando necesites ejecución QuickJS acotada. Las SPA pesadas, píxeles, fidelidad V8, extensiones y desafíos interactivos anti-bot pertenecen a un nivel real de Chrome.

Prueba la demo pública web en vivo antes de instalar. Acepta solo los conjuntos de fuentes públicas fijos que se muestran en la página; no envíes datos privados, cookies ni tareas autenticadas a través de ella. Un endpoint MCP compartido de HTTP Streamable está disponible en https://unchainedsky.com/unbrowser-mcp para pruebas públicas de humo; las sesiones de producción deben usar una instalación local.

Usa unbrowser solo en sitios, cuentas y datos a los que tengas permitido acceder. La detección de desafíos y la importación de cookies no otorgan permiso para eludir controles de acceso ni términos del sitio. Trata las cookies de sesión como credenciales: mantenlas locales, limítalas a la tarea autorizada y nunca las envíes a la demo pública.

Elige el nivel adecuado

Usa unbrowser cuando HTTP solo sea demasiado limitado y un navegador completo sea demasiado costoso. Cuando la página necesite Chrome, la salida le indica al agente que escale en lugar de fingir una compatibilidad que no tiene.

Inicio rápido

Docker — Linux amd64/arm64, ~13 MiB de descarga

docker pull ghcr.io/protostatis/unbrowser:latest

# One-shot navigation
docker run --rm ghcr.io/protostatis/unbrowser:latest \
  navigate https://example.com --json

# Default mode: MCP over stdio
docker run --rm -i ghcr.io/protostatis/unbrowser:latest

La imagen es distroless y se ejecuta como no root: sin shell, gestor de paquetes ni estado persistente. Fija :vX.Y.Z o un digest de imagen en producción.

Python

pipx install pyunbrowser   # recommended on macOS / modern Linux
# or, inside a Python 3.10+ virtual environment:
pip install pyunbrowser

from unbrowser import Client

with Client() as ub:
    ub.navigate("https://news.ycombinator.com")
    for link in ub.query(".titleline > a")[:3]:
        print(link["text"], link["attrs"]["href"])

En macOS, /usr/bin/python3 es 3.9 y no puede instalar la rueda; usa pipx o un Python de Homebrew. La distribución de PyPI es pyunbrowser, mientras que la importación y el ejecutable siguen siendo unbrowser.

MCP

{
  "mcpServers": {
    "unbrowser": {
      "command": "unbrowser",
      "args": ["--mcp"]
    }
  }
}

Superficie mínima: agrega "--mcp-profile", "minimal" para exponer solo navigate/query/extract/help y deja que el agente descubra el resto mediante help(topic). El envoltorio de Python incluye un servidor inteligente de 3 herramientas (search/open/help) como script de consola unbrowser-smart.

{
  "mcpServers": {
    "unbrowser": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "ghcr.io/protostatis/unbrowser:latest"
      ]
    }
  }
}

Consulta la referencia de instalación e interfaz para Cargo, archivos de distribución, compilaciones desde fuente, sesiones de shell persistentes, JSON-RPC crudo y todas las opciones de MCP.

Lo que obtiene un agente

• navigate devuelve un BlockMap: título de página, puntos de referencia, encabezados, elementos interactivos, señales de densidad y un esquema ASCII. Su tamaño depende de la página; está estructurado para planificación, no como una promesa de tokens fijos.
• Referencias de elementos estables (e:142): consulta un elemento una vez y luego haz click, type o submit sin volver a analizar el HTML.
• Cookies y formularios con estado: almacén de cookies, envío de formularios GET y POST codificado en URL, enlaces y redirecciones persisten dentro de una sesión.
• Señales de página y desafíos: density.likely_js_filled, thin_shell y challenge.provider le indican a un agente si debe ejecutar scripts, inspeccionar datos incrustados, detenerse o escalar a una sesión de navegador autorizada.
• Ayudas de enrutamiento en cada resultado: micro_hint (el siguiente paso concreto único), next_tools (candidatos clasificados), avoid (herramientas sin nada sobre lo que actuar) y una taxonomía estable escalation (challenge, thin_shell, partial_result, …) con reintentable/severidad/evidencia — las recomendaciones nunca contradicen a avoid.
• Asistentes estructurados: descubrimiento de rutas, extracción de tarjetas, normalización de tablas, text_main y depuración de selectores cubren flujos de extracción comunes.

Modo script y escalamiento

{"id":1,"method":"navigate","params":{"url":"https://example.com","exec_scripts":true}}

Con exec_scripts: true, los scripts en línea y externos se ejecutan en QuickJS bajo un watchdog acotado. Esto puede materializar hidratación ligera y datos visibles mediante fetch; no es V8 ni un motor de renderizado. Las aplicaciones pesadas de React/Vue/Ember pueden seguir dejando un shell vacío.

Escala a unchainedsky-cli o Unchained cuando una tarea permitida necesite píxeles reales, Canvas/WebGL, Workers, extensiones de navegador, compatibilidad V8, un perfil autenticado o confirmación humana. Cuando el usuario ya haya establecido una sesión autorizada en Chrome, cookies_set puede importar la cookie de sesión requerida localmente hasta que expire; no es una licencia para eludir los controles de un sitio.

Documentación

Licencia

Apache-2.0 — consulta LICENSE.