unbrowser is a stateful, non-visual web runtime for agents, positioned as a "cheap browser channel for agents." It runs as a single native binary without Chrome, sitting between simple curl/WebFetch and a full browser: use it when plain HTTP is too dumb and a full browser is too expensive; when a page truly needs Chrome, the output advises the agent to escalate rather than pretending to have compatibility that does not exist. The official MCP registry identifier is mcp-name: io.github.protostatis/unbrowser.
Main capabilities navigate returns a BlockMap: including the page title, landmarks, headings, interactive elements, density signals, and an ASCII outline. Its size depends on the page, and its structure is aimed at planning rather than a fixed token promise. Stable element references (such as e:142): after querying an element once, you can click, type on, or submit it without re-parsing the HTML. Stateful cookies and forms: cookie jar, GET and URL-encoded POST form submission, links, and redirects are maintained within the session. Page and challenge signals: density.likely_js_filled, thin_shell, and challenge.provider can indicate whether the agent should run scripts, inspect embedded data, stop, or escalate to an authorized browser session. Routing assistance in results: micro_hint (the next concrete action), next_tools (ranked candidates), avoid (tools with no actionable object), and a stable escalation taxonomy (challenge, thin_shell, partial_result, etc.), with retryable/severity/evidence; recommendations never contradict avoid. Structured helpers: route discovery, card extraction, table normalization, text_main, and selector debugging, covering common extraction workflows.
How to use By default, navigate is the fast static/SSR channel; set exec_scripts: true only when constrained QuickJS execution is needed. In script mode, inline and external scripts run in QuickJS under watchdog constraints, and can materialize lightweight hydration and scrape visible data, but it is not a V8, nor is it a rendering engine; heavy React/Vue/Ember applications may still be left with only an empty shell. Regarding installation: the Docker image supports Linux amd64/arm64, pulls about 13 MiB, uses distroless, and runs as non-root (no shell, package manager, or persistent state); in production, pin :vX.Y.Z or the image digest. On macOS, /usr/bin/python3 is 3.9 and cannot install the wheel; use pipx or Homebrew Python instead; the PyPI distribution name is pyunbrowser, while the import and executable remain unbrowser. The minimal interface can add "--mcp-profile", "minimal", exposing only navigate / query / extract / help, letting the agent discover the remaining functionality through help(topic); the Python wrapper provides a 3-tool smart server (search / open / help), and the console script is named unbrowser-smart. For more installation and interface details (Cargo, release archives, building from source, persistent shell sessions, raw JSON-RPC, and all MCP options), see its installation and interface reference.
Applicable scenarios and limitations Suitable for lightweight web discovery and extraction on sites, accounts, and data permitted by authorization. Not suitable for heavy SPAs, pixel-perfect rendering, V8 fidelity, browser extensions, and interactive anti-bot challenges—these belong to the true Chrome tier and should be upgraded to unchainedsky-cli or Unchained. When the user already has an authorized session established in Chrome, cookies_set can import the required session cookies locally until they expire, but this does not constitute permission to bypass site controls. Challenge detection and cookie import do not grant permission to bypass access controls or site terms; session cookies should be treated as credentials, kept local, limited to authorized tasks, and never sent to public demos. Before installing, you can try the public online demo first; it only accepts the fixed set of public sources listed on the page, so do not send private data, cookies, or tasks requiring authentication through it; for public smoke testing, you can use the shared Streamable HTTP MCP endpoint https://unchainedsky.com/unbrowser-mcp，生产会话应使用本地安装。项目采用 Apache-2.0 licensed.
