ascended-browser

A real browser for your AI agent. One command to add.

A real browser for AI agents, as an MCP server. Your agent opens pages, reads them, and acts on them through verified actions: it fills a whole form in one call, picks "Mrs." from a custom React dropdown by name, and is told what the page did in response, instead of clicking coordinates and hoping.

It is the browser from Ascended, packaged on its own: Camoufox (a hardened Firefox that looks like a person's browser to the sites it visits) behind the same tool dispatcher, page reading and result formatting Ascended's own agent uses.

See it work

Three real runs of Claude Code with only this server attached, on live sites. The panel on the side is Claude Code's own transcript: every tool call it made and what came back, errors included, with the real elapsed time. Waiting is cut and tool time plays faster; the pointer, device frames, devtools panels and outlines are drawn afterwards from the server's event log (demo/record_demo.py), so they sit on what the agent really touched and read. The full unedited screen recordings are in videos/unedited/ (the browser is driven through Playwright, so no OS pointer appears in them).

Front-end QA. react.dev on a phone and a tablet, dark/light, before/after screenshots, an audit outlining the real offending elements, console and network.

Browsing. Types into Wikipedia's search, finds a fact in the article, then searches YouTube and plays the first video.

Real forms. booking.com: popup, destination autocomplete, date picker, search, sort by price.

Click any clip for the full-quality MP4.

Install

From Python (3.11 or newer) or from npm; both run the same server.

uvx ascended-browser doctor          # checks the machine; downloads nothing
uvx ascended-browser fetch           # downloads the browser now (~700 MB; otherwise on first use)

npx -y ascended-browser doctor       # the same, from npm

The browser is Camoufox 135.0.1-beta.24, the build every test here ran on; it is pinned, so a newer Camoufox release never changes what your agent drives, and any other Camoufox you have installed is left as it is. Run fetch once before adding the server to an agent, so its first tool call does not wait for the download.

The npm package is a small launcher: it runs the Python package with uvx when uv is installed (uv brings its own Python), else pipx, else a private venv made with your Python 3.11+. Use whichever command you prefer in the configs below (npx -y ascended-browser in place of uvx ascended-browser).

Linux: install xvfb to keep the browser on a virtual display (closest to a real screen); without it the browser runs headless. On a display, browser_viewport resizes the real window, so phone and tablet checks reflow the page at true breakpoints.

Add it to your agent

Claude Code

claude mcp add ascended-browser -- uvx ascended-browser
# or: claude mcp add ascended-browser -- npx -y ascended-browser

Codex

codex mcp add ascended-browser -- uvx ascended-browser

Whether Codex asks before each browser action follows the permission mode you pick in Codex: under Full access it just runs them; under Ask for approval it asks first. In a sandboxed mode, codex exec cannot ask and fails every call: use Full access, or pre-approve this server's tools by adding default_tools_approval_mode = "approve" under [mcp_servers.ascended-browser] in ~/.codex/config.toml.

opencode (opencode.json)

{
  "mcp": {
    "ascended-browser": { "type": "local", "command": ["uvx", "ascended-browser"], "enabled": true }
  }
}

Cursor, Windsurf, Claude Desktop and other clients: a stdio server with command uvx and args ["ascended-browser"], or command npx and args ["-y", "ascended-browser"].

Tools

Tool	What it does
browser_open	Open a URL (or several at once) and return what is on the page, each control with a ref
browser_observe	Look at the page again, or narrow to a region, a query or a filter
browser_act	navigate, click, fill, fill_form, select, check, date, press, upload, scroll, wait, sequence: each verified, each answered with what changed
browser_extract	Read the page's text and field state, find a phrase, list every match of a CSS selector with its text and attributes (every product link, every price), or read=console, read=network, read=inspect, read=audit, read=design to debug a page
browser_screenshot	A picture, when an observation cannot describe it: canvas, charts, visual layout; compare_with diffs against an earlier picture or another tab
browser_viewport	Resize to phone/tablet/desktop (Linux), emulate dark mode, reduced motion, forced colors or offline
browser_evaluate	Read-only JavaScript, policy-checked
browser_tabs	List, close or sleep tabs
browser_flow	Record a task once, replay it on the next page with new values
wait_for_bot_wall	Wait out a "checking your browser" page; press a Turnstile/reCAPTCHA checkbox if one blocks a form

Long results come back clipped, with an evidence_ref that browser_extract pages through, so a huge page cannot flood the agent's context.

Settings

Variable	Default
ASCENDED_BROWSER_WINDOW	hidden	show opens a visible window
ASCENDED_DATA_DIR	~/.local/share/ascended/browser	Browser profile (sign-ins persist), session files
ASCENDED_RESULT_MAX_CHARS	24000	Longer results are clipped with an evidence_ref
ASCENDED_SETTING_<KEY>		Any browser setting, e.g. ASCENDED_SETTING_BROWSER_WORKSPACE_OBSERVE_FORMAT=outline
ASCENDED_LOG_LEVEL	WARNING	Logs go to stderr

Limits

• Window resizing (browser_viewport phone/tablet/desktop presets or any width and height) works on Linux: on the package's own virtual display by default, or on your X11 display with ASCENDED_BROWSER_WINDOW=show. On macOS and Windows the window keeps its launch size; emulation (dark mode, reduced motion, forced colors, offline) works everywhere. Screenshot grids across several sizes in one call are not included.
• Model-backed features of the Ascended app are not in this package: schema-shaped extraction (a model reads the page into your JSON shape) and saved logins (browser_login). Their tools and parameters are not exposed, so an agent never sees them. Everything listed under Tools runs without a model.
• One server process is one browser session: tabs and refs last until your client disconnects; the profile (cookies, sign-ins) lasts across sessions. Several sessions can run at once: the first one uses the saved profile, and any other one started while it runs gets its own copy, already signed in to whatever the saved profile was. Sign-ins made in a copy end with that session.

How it is built

src/ascended_browser/_app is generated from Ascended by scripts/sync_from_ascended.py: the browser modules copied as they are, the browser tool dispatcher and result formatter extracted by reachability, and every import of the rest of the app rewritten to runtime/ (small standalone stand-ins). The sync refuses any app import it cannot map.

Tested with Ascended's own stress harnesses run against this package (tests/stress/), a client-side MCP smoke test (tests/smoke_mcp.py), and live-website tasks given to real agents (tests/agents/).

What has been verified so far: Linux (Python 3.11, 3.12 and 3.14), with Claude Code and Codex (0.160) on live-site tasks, opencode on a navigation task, and the npm launcher through uvx and through its own venv. macOS and Windows should work headless or with a visible window, but are untested.

License

MIT. The bundled axe-core (_app/browser_vendor/axe-core) is MPL-2.0 and keeps its notice in the file.