Eyebrowse

👁️ EyeBrowse

A stealthy, LLM-drivable browser engine — one codebase, two faces.

A Python library *and* an MCP server for driving a real, hard-to-detect browser, so legitimate automation isn't false-flagged or IP-banned by Cloudflare, DataDome, Akamai, or PerimeterX. Built on CloakBrowser — a stealth Chromium (Chrome/146) that's a Playwright drop-in — so EyeBrowse gets the full Chrome DevTools Protocol: trusted cursorless clicks, deep network inspection, MHTML, PDF, and native video.

▶ Full-quality MP4: docs/demo.mp4 — an AI agent drives EyeBrowse over MCP: clears a Cloudflare check, then reads real docs (asyncio · httpx · MDN).

---

Why EyeBrowse?

• 🥷 Stealth by default — engine-level fingerprint spoofing (geoip + humanize on out of the box, novel fingerprint per launch); navigator.webdriver masked; viewport auto-sized to the spoofed screen. No puppeteer-extra band-aids — the anti-detection is *compiled into the browser*.
• 🤖 Built for LLMs — pages are read as an ARIA tree with `[ref=…]` handles; the model acts by ref (click/type/hover), not by brittle CSS or raw pixels. Cross-origin iframes, shadow DOM, popups — handled.
• ⚡ Chrome DevTools Protocol — trusted, cursorless clicks by node ref (Input.dispatchMouseEvent), raw Network/Performance/Emulation access, MHTML snapshots, PDF export, and native video — all reachable as tools.
• 🧰 **Library *and* MCP from one codebase — a clean Python API (`EyeBrowse` + `Session`), mirrored 1:1 by a thin MCP server (85 browser_* tools**) for Claude Code and any MCP client.
• 🪟 Never boxed in — the curated high-level API doesn't hide Playwright: reach session.page / .context / .browser for anything it doesn't wrap.
• 🔋 Batteries included — multi-session, proxy + identity rotation, API-mode captcha solvers, native video, full HAR capture, and clean-markdown extraction.

Scope. EyeBrowse is a low-level browser *engine* — it holds no workflow logic.

Consumers decide *what* to do; the engine provides *what's possible*.

Contents

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

Quickstart

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())

…or wire it into Claude Code (or any MCP client) — see Use over MCP.

Install

From 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)

From source (development)

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 (pinned <3.13). Engine: cloakbrowser>=0.3 (stealth Chromium, Chrome/146), on playwright 1.60 and mcp 1.27.

Features

Full per-tool reference: [docs/TOOLS.md](docs/TOOLS.md) (85 tools across 18 groups).

How EyeBrowse compares

Fair-use note: each project targets a different niche — this compares them on the axes EyeBrowse optimizes for (stealth + LLM-drivable + one library/MCP codebase), not as an overall ranking.

Use as a library

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())

Run the included proof: uv run python examples/direct_usage.py.

Use over MCP

EyeBrowse ships an MCP server (eyebrowse-mcp, FastMCP over stdio). Add it to any MCP client.

Claude Code (CLI):

claude mcp add eyebrowse -- eyebrowse-mcp

Any MCP client (JSON config):

{

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

Then drive the loop: browser_navigate(url) → read the snapshot → act by ref (browser_click / browser_type / …). A default session is auto-created, so most tools just work. Full list: [docs/TOOLS.md](docs/TOOLS.md).

Proxy & identity (optional)

Runs proxyless by default (geoip still aligns locale/timezone to your real IP). Add a proxy only when you want one:

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

Set a default once via EYEBROWSE_PROXY_* in .env, eb.set_static_proxy(...), or a custom ProxyProvider for rotation. Over MCP: browser_new_session(proxy_url=…) / browser_new_identity(proxy_url=…) / browser_set_proxy(…).

reCAPTCHA v3 / reputation gates are score-based and key off IP + session reputation — a

fresh browser on a flagged IP fails regardless of stealth. Pair EyeBrowse with a clean

residential proxy.

Extraction

eb.extract() (or browser_extract) hands the rendered HTML to Crawl4AI's raw: feed and returns clean, pruned markdown — no LLM is called and no LLM keys are ever read; the consuming agent does any structuring.

md  = await eb.extract()                            # markdown string

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

Recording

Native video — Playwright records the whole session to a .webm, written on close. The path is known up-front; the file finalizes when the session closes:

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)

Over MCP: browser_new_session(record_video=True) → browser_video_path. Want a GIF for a README? Convert the .webm with ffmpeg (ffmpeg -i demo.webm demo.gif). The demo at the top was captured this way — see `examples/make_demo.py`.

How it works

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, A