protostatis/unbrowser

**The cheap browser pass for agents. One native binary. No Chrome.**
**Official MCP Registry identity:** mcp-name: io.github.protostatis/unbrowser
unbrowser is a stateful, non-visual web runtime for agents. It sits between curl/WebFetch and a real browser: it retains cookies and DOM state, returns queryable element refs, handles links and HTML forms, detects challenge and SPA signals, and can run bounded QuickJS page scripts when static HTML is not enough.
> **Default navigate is a fast static/SSR pass.** Set exec_scripts: true only when you need bounded QuickJS execution. Heavy SPAs, pixels, V8 fidelity, extensions, and interactive anti-bot challenges belong in a real Chrome tier.
Try the live public-web demo before installing. It accepts only the fixed public source sets shown on the page; do not send private data, cookies, or authenticated tasks through it. A shared Streamable HTTP MCP endpoint is available at https://unchainedsky.com/unbrowser-mcp for public smoke tests; production sessions should use a local install.
Use unbrowser only on sites, accounts, and data you are permitted to access.
Challenge detection and cookie import do not grant permission to bypass access
controls or site terms. Treat session cookies as credentials: keep them local,
scope them to the authorized task, and never send them to the public demo.
Pick the right tier
| Need | curl / WebFetch | unbrowser | Real Chrome |
|---|---|---|---|
| Static / SSR HTML | raw response | structured BlockMap + DOM queries | full browser |
| Cookies, links, HTML forms | DIY | built in | built in |
| Client-side page scripts | ❌ | bounded QuickJS, opt-in | V8 |
| Pixels, Canvas, WebGL, Workers, extensions | ❌ | ❌ | ✅ |
| Agent-oriented output | DIY parsing | element refs, page signals, structured extraction | DIY CDP / DOM parsing |
| Interactive access challenge | ❌ | detect + stop or escalate | authorized browser / human confirmation |
Use unbrowser when HTTP alone is too dumb and a full browser is too expensive. When the page needs Chrome, the output tells the agent to escalate rather than pretending compatibility it does not have.
Quick start
Docker — Linux amd64/arm64, ~13 MiB pull
The image is distroless and runs as non-root: no shell, package manager, or persistent state. Pin :vX.Y.Z or an image digest in production.
Python
On macOS, /usr/bin/python3 is 3.9 and cannot install the wheel; use pipx or a Homebrew Python. The PyPI distribution is pyunbrowser, while the import and executable remain unbrowser.
MCP
Minimal surface: add "--mcp-profile", "minimal" to expose only navigate/query/extract/help and let the agent discover the rest via help(topic). The Python wrapper ships a 3-tool smart server (search/open/help) as the unbrowser-smart console script.
Docker MCP configuration
See installation and interface reference for Cargo, release archives, source builds, persistent shell sessions, raw JSON-RPC, and all MCP options.
What an agent gets
- **navigate returns a BlockMap**: page title, landmarks, headings, interactives, density signals, and an ASCII outline. Its size is page-dependent; it is structured for planning rather than a fixed-token promise.