Unbrowser

What protostatis/unbrowser MCP server does

The protostatis/unbrowser MCP server provides agent-oriented access to web pages without launching Chrome. It uses a native binary and maintains session state, including cookies and the current DOM. Results are returned as structured BlockMaps rather than raw page content, giving an agent page titles, landmarks, headings, interactive elements, density signals, and an ASCII outline for planning.

Stable element references such as e:142 let an agent query an element and later act on it with operations such as clicking, typing, or submitting. The runtime supports links, redirects, GET forms, and URL-encoded POST forms within a session. It also reports signals for JavaScript-heavy pages and access challenges so an agent can decide whether to inspect further, stop, or escalate.

How it works

By default, navigation performs a fast static or server-rendered pass. When static HTML does not expose the needed content, the protostatis/unbrowser MCP server can run bounded QuickJS execution by setting exec_scripts to true. This may materialize light hydration and fetch-visible data, but it is not a V8-compatible browser or rendering engine. Heavy React, Vue, or Ember applications may still produce an incomplete shell.

Each result includes routing guidance such as a concrete next step, ranked candidate tools, tools that have nothing useful to act on, and an escalation classification. Signals can indicate likely client-side filling, a thin shell, a detected challenge provider, or a partial result. These outputs help an agent choose between another unbrowser operation and an authorized browser workflow.

The server can run through MCP over standard input and output. It can also be used through a one-shot command-line navigation mode or the Python client. A shared HTTP endpoint and public demo are documented for public smoke tests, while local installation is recommended for production sessions and private data.

Setup and configuration

Install the Python distribution with pipx install pyunbrowser, or install it inside a Python 3.10 or newer virtual environment with pip install pyunbrowser. The distribution name is pyunbrowser, while the executable and Python import use unbrowser. On macOS, use a newer Python because the system Python 3.9 cannot install the wheel.

For MCP clients, configure the executable with unbrowser --mcp. The optional --mcp-profile minimal setting exposes only navigate, query, extract, and help; the agent can discover additional operations through help(topic). Docker users can run the published ghcr.io/protostatis/unbrowser:latest image with standard input attached. Production Docker deployments should pin a version tag or image digest.

Tools and capabilities

The protostatis/unbrowser MCP server supports capabilities including:

• Navigating pages and returning structured BlockMaps.
• Querying DOM elements and using stable element references.
• Clicking, typing, and submitting forms.
• Following links and retaining cookies and DOM state.
• Extracting cards, tables, main text, routes, and other structured page data.
• Running bounded QuickJS scripts when explicitly enabled.
• Detecting thin shells, likely JavaScript-filled pages, and access challenges.

The Python wrapper also provides a three-tool smart server with search, open, and help console operations.

Limitations and notes

The protostatis/unbrowser MCP server does not provide pixels, Canvas, WebGL, Workers, browser extensions, or full V8 behavior. It is not intended to solve interactive anti-bot challenges or replace an authorized Chrome session when a site requires human confirmation. Challenge detection and cookie import do not bypass access controls or grant permission to use a site.

Cookie imports should be treated as credentials and kept local, scoped to authorized work. Do not send private data, cookies, or authenticated tasks through the public demo or shared public endpoint. Use the runtime only with sites, accounts, and data you are permitted to access. When a task needs a real browser profile, rendering fidelity, or human interaction, the documented escalation path is an authorized browser tier.