EyeBrowse

---

¿Por qué EyeBrowse?

• 🥷 Sigilo por defecto — suplantación de huella digital a nivel de motor (geoip + humanize activados de fábrica, huella novedosa por lanzamiento); navigator.webdriver enmascarado; viewport ajustado automáticamente a la pantalla suplantada. Sin parches puppeteer-extra — la anti-detección está compilada en el navegador.
• 🤖 Diseñado para LLMs — las páginas se leen como un árbol ARIA con manejadores [ref=…]; el modelo actúa por referencia (click/type/hover), no por CSS frágil ni píxeles crudos. Iframes de origen cruzado, shadow DOM, ventanas emergentes: manejados.
• ⚡ Protocolo Chrome DevTools — clics confiables sin cursor por referencia de nodo (Input.dispatchMouseEvent), acceso crudo a Network/Performance/Emulation, capturas MHTML, exportación PDF y video nativo — todo accesible como herramientas.
• 🧰 Biblioteca y MCP desde un solo código base — una API de Python limpia (EyeBrowse + Session), reflejada 1:1 por un servidor MCP delgado (85 herramientas browser_*) para Claude Code y cualquier cliente MCP.
• 🪟 Nunca limitado — la API de alto nivel curada no oculta Playwright: accede a session.page / .context / .browser para cualquier cosa que no envuelva.
• 🔋 Todo incluido — multi-sesión, rotación de proxy + identidad, solucionadores de captcha en modo API, video nativo, captura HAR completa y extracción de markdown limpio.

Alcance. EyeBrowse es un motor de navegador de bajo nivel — no contiene lógica de flujo de trabajo. Los consumidores deciden qué hacer; el motor proporciona lo que es posible.

Contenido

Quickstart · Install · Features · Compare · Library · MCP · Proxy & identity · Extraction · Recording · How it works · Caveats · Tools · License

Inicio rápido

pip install eyebrowse
# The stealth-Chromium binary downloads automatically on first launch — nothing else to run.

import asyncio
from eyebrowse import EyeBrowse

async def main():
    eb = EyeBrowse()                          # stealth defaults: geoip · humanize
    async with eb.session() as s:
        await s.navigate("https://example.com")
        print(await s.snapshot())             # ARIA tree with [ref=...] handles
        await s.click("e6")                   # act on a ref from the snapshot
    await eb.aclose()

asyncio.run(main())

…o conéctalo a Claude Code (o cualquier cliente MCP) — consulta Uso a través de MCP.

Instalación

Desde PyPI

pip install eyebrowse                 # or: uv pip install eyebrowse
# CloakBrowser fetches its Chromium binary lazily on first launch — nothing to run.
pip install "eyebrowse[extract]"     # optional: + Crawl4AI markdown extraction (heavier)

Desde el código fuente (desarrollo)

git clone https://github.com/Evil-Bane/eyebrowse && cd eyebrowse
uv sync                              # core engine  (add --extra extract for Crawl4AI)
cp .env.example .env                 # only if you use a proxy / captcha keys

Python 3.12 (fijado <3.13). Motor: cloakbrowser>=0.3 (Chromium sigiloso, Chrome/146), en playwright 1.60 y mcp 1.27.

Características

🥷 Sigilo	Suplantación de huella digital del Chromium parcheado de CloakBrowser (novedoso --fingerprint por lanzamiento); geoip + humanize por defecto; webdriver enmascarado; viewport ajustado a la pantalla suplantada.
🤖 Interacción con LLM	aria_snapshot(mode="ai") → árbol ARIA + manejadores [ref]; clic / escribir / pasar el cursor / seleccionar / arrastrar / subir archivos / diálogos / teclado; también ratón por coordenadas.
⚡ CDP	clic confiable sin cursor por referencia, CDP crudo (Network / Performance / Emulation), captura MHTML, exportación PDF.
🪟 Frames y DOM	enrutamiento de iframes de origen cruzado por referencia, penetración de shadow DOM, cambio de ventanas emergentes/nuevas pestañas, evaluate dentro de cualquier frame.
🗂 Multi-sesión	sesiones sigilosas independientes, cada una con su propio contexto / identidad / proxy.
🌐 Red	inspeccionar solicitudes/respuestas (incl. cuerpos XHR/fetch y tramas WebSocket), bloquear URLs, simular respuestas, desconectarse, exportación HAR completa.
💾 Estado	cookies, localStorage y sessionStorage (CRUD), guardar/recargar storage_state.
🪪 Rotación de identidad	huella nueva + perfil aislado + proxy emparejado; ProxyProvider residencial conectable.
🧩 Captcha	solucionadores en modo API conectables (CapSolver / 2Captcha / CapMonster / NextCaptcha) + TOTP — sin extensión de navegador.
📄 Extracción	alimentación de Crawl4AI raw: → markdown limpio y eficiente en tokens (sin LLM, sin claves API).
🎥 Captura	capturas de pantalla, seguimiento de Playwright y video nativo (.webm).
✅ Verificar y depurar	aserciones, resaltado de elementos, generación de localizadores, emulación de geolocalización/cabeceras.

Referencia completa por herramienta: docs/TOOLS.md (85 herramientas en 18 grupos).

Cómo se compara EyeBrowse

	EyeBrowse	Playwright MCP	browser-use	playwright-stealth
Anti-detección compilada en el navegador	✅	❌	❌	⚠️ Parches JS
Modelo de interacción [ref] ARIA nativo para LLM	✅	✅	✅	❌
Incluye un servidor MCP	✅ (85 herramientas)	✅	⚠️ parcial	❌
Un solo código base: biblioteca y MCP de Python	✅	Solo MCP	Solo biblioteca	Solo biblioteca
CDP completo (clics confiables · red · MHTML · PDF · video)	✅	⚠️ parcial	❌	⚠️ parcial
Captcha (modo API) + TOTP	✅	❌	❌	❌
Rotación de proxy + identidad integrada	✅	❌	⚠️ parcial	❌
Iframes de origen cruzado · shadow DOM · ventanas emergentes	✅	✅	⚠️ parcial	n/a

_{Nota de uso justo: cada proyecto apunta a un nicho diferente — esto los compara en los ejes que EyeBrowse optimiza (sigilo + manejable por LLM + un solo código base de biblioteca/MCP), no como una clasificación general.}

Uso como biblioteca

import asyncio
from eyebrowse import EyeBrowse

async def main():
    eb = EyeBrowse()                           # stealth defaults
    try:
        async with eb.session() as s:          # a stealth session (auto-closed)
            await s.navigate("https://example.com")
            print(await s.snapshot())          # ARIA tree with [ref=...] handles
            await s.click("e6")                # act on a ref
            await s.type("e8", "hello", submit=True)
            png = await s.screenshot(full_page=True)
            title = await s.page.title()        # full Playwright power when you need it
    finally:
        await eb.aclose()

asyncio.run(main())

Ejecuta la prueba incluida: uv run python examples/direct_usage.py.

Uso a través de MCP

EyeBrowse incluye un servidor MCP (eyebrowse-mcp, FastMCP sobre stdio). Añádelo a cualquier cliente MCP.

Claude Code (CLI):

claude mcp add eyebrowse -- eyebrowse-mcp

Cualquier cliente MCP (configuración JSON):

{
  "mcpServers": {
    "eyebrowse": {
      "command": "eyebrowse-mcp"
    }
  }
}

Luego maneja el bucle: browser_navigate(url) → lee la instantánea → actúa por referencia (browser_click / browser_type / …). Se crea automáticamente una sesión predeterminada, por lo que la mayoría de las herramientas funcionan directamente. Lista completa: docs/TOOLS.md.

Proxy e identidad (opcional)

Se ejecuta sin proxy por defecto (geoip aún alinea la configuración regional/zona horaria con tu IP real). Añade un proxy solo cuando lo necesites:

await eb.new_session(proxy="http://user:pass@residential.example:8080")
await eb.rotate_identity(proxy="socks5://host:1080")   # fresh fingerprint + paired IP
await eb.new_session(no_proxy=True)                     # force proxyless

Establece un valor predeterminado una vez mediante EYEBROWSE_PROXY_* en .env, eb.set_static_proxy(...), o un ProxyProvider personalizado para rotación. A través de MCP: browser_new_session(proxy_url=…) / browser_new_identity(proxy_url=…) / browser_set_proxy(…).

reCAPTCHA v3 / puertas de reputación se basan en puntuaciones y dependen de la reputación de IP + sesión — un navegador nuevo en una IP marcada falla independientemente del sigilo. Combina EyeBrowse con un proxy residencial limpio.

Extracción

eb.extract() (o browser_extract) entrega el HTML renderizado a la alimentación raw: de Crawl4AI y devuelve markdown limpio y podado — no se llama a ningún LLM y nunca se leen claves de LLM; el agente consumidor realiza cualquier estructuración.

md  = await eb.extract()                            # markdown string
res = await eb.extract(output_path="data/page.md")  # → {"path": ..., "chars": ...}

Grabación

Video nativo — Playwright graba toda la sesión en un .webm, escrito al cerrar. La ruta se conoce de antemano; el archivo se finaliza cuando la sesión se cierra:

s = await eb.new_session(record_video=True)
# ... drive the browser ...
print(await s.video_path())          # path is known up-front; file finalizes on close
await eb.close_session(s.id)

A través de MCP: browser_new_session(record_video=True) → browser_video_path. ¿Quieres un GIF para un README? Convierte el .webm con ffmpeg (ffmpeg -i demo.webm demo.gif). La demo de arriba se capturó así — consulta examples/make_demo.py.

Cómo funciona

CONSUMERS                         ENGINE (library: eyebrowse/)
 Claude Code  ──MCP──▶  mcp/  ──▶  EyeBrowse façade (public API)
 your code   ─ import ──────────▶   ├─ BrowserEngine (CloakBrowser / stealth Chromium)
 any MCP client                     ├─ proxy / identity rotation (pluggable)
                                    ├─ captcha solvers (pluggable, API-mode)
                                    └─ Crawl4AI (raw: feed) → clean markdown

La fachada (EyeBrowse + Session) es el producto; el adaptador MCP es un envoltorio delgado 1:1 sobre ella. La API de alto nivel está curada y es amigable con LLM — no es una reimplementación de todo Playwright — y los objetos crudos page / context / browser están siempre a un atributo de distancia. El lanzador es la única capa específica del motor; todo lo demás es Playwright puro.

Advertencias

Vale la pena saberlo:

• evaluate se ejecuta en el mundo principal de la página (los globales de la página son accesibles). Para sobrescribir los globales de widgets de una página y disparar una devolución de llamada del sitio (por ejemplo, para captcha), EyeBrowse inyecta un <script> para que el código se ejecute en el mundo de la página — consulta captcha/inject.py.
• La exportación HAR cierra la sesión — Playwright solo vacía el búfer HAR cuando el contexto se cierra. Usa el patrón de punto de control: browser_storage_state → browser_har_export → browser_new_session(storage_state=...). Para el HAR de Chrome rico en iniciadores (pilas de llamadas JS), accede al dominio Network.* a través de browser_cdp_send.
• El video nativo es .webm — conviértelo a GIF/MP4 con ffmpeg si necesitas otro formato.

Estructura del proyecto

eyebrowse/
  api.py            EyeBrowse façade — the single public entry point
  config.py         settings / secrets (pydantic-settings)
  snapshot.py       aria_snapshot(mode="ai") + aria-ref= resolution
  proxy.py          ProxyConfig + pluggable ProxyProvider
  identity.py       Identity + random_identity() (isolated profile dir)
  extract.py        Crawl4AI raw: feed → markdown (lazy, optional dep)
  engine/           engine.py (CloakBrowser launch) + session.py (verbs + registry)
  captcha/          solver ABC + 4 providers + DOM detect/inject
  mcp/              FastMCP server + state + tools/ (18 groups · 85 tools)
examples/direct_usage.py   library proof (no MCP)
examples/make_demo.py      the native-video demo above
docs/TOOLS.md              full tool reference

Las notas de compilación, la justificación de fijación de versiones y el comportamiento verificado del motor viven en CLAUDE.md.

Uso responsable

EyeBrowse maneja un navegador real con características de anti-detección. Úsalo solo contra sitios que poseas o para los que estés explícitamente autorizado a automatizar, y dentro de sus términos y la ley aplicable.

Licencia

MIT © Evil-Bane