ascended-browser
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ascended-browser Search Wikipedia for the capital of Australia and summarize it"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A local, open-source browser MCP server for Codex CLI, Claude Code and other MCP clients. Use it for interactive browser automation and front-end QA: inspect console logs and network requests, check responsive layouts, and collect screenshots alongside what happened on the page.
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.
Ascended is my own private agent workspace; this package extracts its browser so it can run 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.
Start with a QA check
Read the documentation site: QA setup and interrupted-action reproduction.
Running Codex CLI over SSH and missing a browser? Connect a browser MCP on your Linux dev box with setup commands, localhost guidance and alternatives.
Practical recipes with real local-fixture screenshots:
Set up a browser MCP for Codex CLI or Claude Code and check your app. The guide covers installation, a copy-paste QA prompt, console and network inspection, bug-report structure, and what to do after an interrupted action.
Check a local app: walk through a flow and report errors before changing code.
Inspect the evidence: read failed requests and console errors, then capture the broken state.
Use a Linux dev box: run the client, MCP server and app on the same machine; the guide explains how localhost behaves when you connect over SSH.
This is agent-assisted exploratory QA, not a replacement for deterministic regression tests or a validated CI integration. Browser MCP tools are also available from projects such as Playwright MCP and Chrome DevTools MCP; console and network inspection are not exclusive to this server.
Related MCP server: mcp-web-search
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.
Saved logins. You save a login once; the agent signs in with it and never sees it. Built from a real run (demo/login_demo.py, then demo/login_explainer.py): the CLI's output, the screen, and the exact text and pictures the agent got back.
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 npmThe 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-browserCodex
codex mcp add ascended-browser -- uvx ascended-browserWhether 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 |
| Open a URL (or several at once) and return what is on the page, each control with a ref |
| Look at the page again, or narrow to a region, a query or a filter |
|
|
| Read the page's text and field state, |
| A picture, when an observation cannot describe it: canvas, charts, visual layout; |
| Resize to phone/tablet/desktop (Linux), emulate dark mode, reduced motion, forced colors or offline |
| Read-only JavaScript, policy-checked |
| List, close or sleep tabs |
| Record a task once, replay it on the next page with new values |
| Sign in with a login you saved (see Saved logins); the agent never sees its values |
| 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.
Every action waits for the page to settle, under a hard timeout, and says
when its effect could not be confirmed. If a turn ends while one is still
running, the next turn is told instead of finding a page it cannot explain:
an interrupted click (you stopped the turn) is named in the next result for
that tab, and an action whose server died (claude -p ending, an SSH session
dropping) is listed with the first result of the next session, so the agent
checks before it repeats an order or a form.
Saved logins
Save a login once and the agent can sign in with it, without ever seeing it.
uvx ascended-browser login add github.com --username you@example.com # prompts for the password
uvx ascended-browser login add accounts.example.com --name Work --totp # also a TOTP secret (or otpauth:// URI)
uvx ascended-browser login list # names, usernames, sites; never passwords
uvx ascended-browser login edit Work --password # change only what you pass
uvx ascended-browser login remove WorkThe site is the host of the sign-in page (accounts.example.com, not
example.com, when they differ); pass several for one account on several
hosts. Passwords and TOTP secrets come from a hidden prompt, or from stdin
with --password-stdin, never from the command line, where they would end up
in shell history and the process list.
Then ask your agent to sign in. browser_open tells it a saved login exists
for the page, and browser_login finds the username, password and
one-time-code fields and types the values in (submit: true also presses
the button). What the agent gets:
Every tool result is scrubbed of every saved username, password and TOTP secret, also URL-encoded, JSON- or HTML-escaped:
browser_observe,browser_evaluate(readinginput.valuereturns[redacted]),browser_extract(page text, field values, network bodies) and action results. A page that prints "Signed in as you@example.com" reads as "Signed in as [redacted]".Every screenshot is masked before it reaches the agent: password, card and one-time-code fields, username and email fields, and any saved value shown as page text.
For sites a saved login cannot fill (single sign-on, passkeys, a CAPTCHA, a code sent by email), sign in by hand once:
uvx ascended-browser signin https://example.com/login # opens the browser; sign in, then press EnterThe cookies stay in the browser profile that every later agent session starts from. Close running agent sessions first, so the sign-in lands in the saved profile rather than a session's copy.
The vault is logins.db in the data directory, readable only by your user,
and not encrypted (like gh or aws credentials files). The scrubbing and
masking cover what the browser tools return. An agent that also has a
shell or file tools (Claude Code, Codex) runs as you and can read any file you
can, this one included. Deny its file tools the path (in Claude Code,
"deny": ["Read(~/.local/share/ascended/**)"] under permissions in
~/.claude/settings.json) and keep shell commands on approval; an agent free
to run any command can still reach the file. Values shorter than 4 characters
are not scrubbed, and a value the page changes (the last four digits of a
card, say) is not matched.
Settings
Variable | Default | |
| hidden |
|
|
| Browser profile (sign-ins persist), saved logins ( |
|
| Longer results are clipped with an |
| Any browser setting, e.g. | |
|
| Logs go to stderr |
Limits
Window resizing (
browser_viewportphone/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 withASCENDED_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.Schema-shaped extraction (a model reads the page into your JSON shape) is an Ascended app feature that needs a model, so it is not in this package and its parameters are not exposed. 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 my Ascended app by
scripts/sync_from_ascended.py: the browser modules taken unchanged, 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/). Saved logins have
their own: tests/test_logins.py (the vault CLI and the scrubber),
tests/login_redaction_mcp.py (a real client signs in on a page that echoes
the login into its text, DOM and network, and no tool may show it; with
tesseract installed it also reads the screenshots) and
tests/signin_persists.py.
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.
Available Tools
11 toolsbrowser_actA
Perform one verified action in a leased tab. action.kind must be navigate|click|fill|fill_form|sequence|select|check|date|press|upload|scroll|wait (action.type is accepted as an alias for kind; type=type means fill). ref must be an exact ref=e… token from the newest page/observe/extract result for this tab — labels and row numbers are rejected; CSS/XPath/text selectors are not an agent-facing escape hatch. Reuse the fresh refs returned in an action's page; do not observe again after every field. A successful act returns either page (the page it produced, with fresh refs) or page_unchanged: true, meaning the URL and visible text are what your last observation showed and its refs still apply — observe again only for a different view (query, selector, region). Batch stable fields with fill_form, which reports each field separately. For anything that picks from a list (native selects, custom ARIA comboboxes and dropdowns, type-to-search boxes) use kind=select with option= and optional query=; this performs and verifies open/filter/choose in one call. For anything with a checked or selected state, including list items, use kind=check with checked=true|false. Independent calls for distinct tab_ids may be issued together; calls targeting one tab remain ordered. Use sequence for a short reversible multi-step workflow when later-page targets can be named semantically. Every step is re-resolved from current page state, authority is rechecked, and the sequence stops before dispatch when an exact expect_before guard or a unique target is missing; use expect_after to guard a planned transition. Do not place a consequential final submit in a sequence. until waits inside the call for a late effect (redirect, async save, hot reload); kind=wait only waits. The same select fields can be included in fill_form. For a reversible draft/save action, a click receipt with state=network_effect_observed, a successful same-origin non-read response, matching control readback, and the page's save status is sufficient browser evidence. Do not activate unrelated controls, inspect hidden databases, or use shell/page scripts solely to obtain stronger private persistence proof. upload attaches files to an input[type=file] ref (or file_chooser=true with an observed attachment button ref) and is the ONLY way to do so — fill rejects file inputs. For a request such as 'keep scrolling until I stop you', use one scroll action with duration_seconds instead of spending repeated model rounds; cancelling/replacing the run stops it.
Inputs: action (required), tab_id (required).
browser_evaluateA
Run policy-gated read-only JavaScript in a tab only when browser_extract or browser_observe cannot return the required fact. For visible page text, labels, controls, or a region owned by aria-controls, use browser_extract instead; for computed styles, colors, fonts, sizes, icons or backgrounds, browser_extract read=design (the page, or one component with target_ref) or read=inspect (one element's box and styles).
Inputs: tab_id (required), function (required), arg.
browser_extractA
Extract the complete current visible content and structured field/page state from a tab. Pass target_ref to scope a fresh read to an observed content block, control or the ARIA region it owns. This is a fresh high-level read, not a change-only observation. If a large result returns evidence_ref and next_cursor from browser_extract, continue it with this same tool. Do not continue a managed-output reference from browser_open, browser_observe, or browser_act; start a fresh extraction with tab_id and instruction instead. Pass selector for an instant CSS query instead of a full read: it counts and lists matching elements (tag, text, requested attributes, and the ref of any match already in the current observation) without building a snapshot, e.g. every product link's href, how many rows a table has, or each card's price. read=console|network reads the tab's logs (with same-site error bodies); read=inspect with target_ref says why a click is refused or a control will not take a value: what receives the click there, what covers or clips it, disabled state, styles. read=design returns how the page looks in CSS terms: variables, colors by use, type scale, radii, shadows, spacing and layout regions with sizes; target_ref limits it to one component. read=audit audits the page you are on (a deployed or localhost site): accessibility violations (axe-core) with the ref of each element, load timings and weight, title/lang/description/headings/alt gaps, broken same-origin links and console errors, worst first.
Inputs: tab_id (required), find, read, level, +15 more.
browser_flowA
Record and replay browser work. Every verified browser_act on a tab is recorded (targets by what they are, not by ref; passwords and other secrets never). After a task succeeds once, action=save turns that tab's recorded steps into a flow; action=run replays it on a tab with no model call between steps, re-finding each element on the live page, so repeating the task (the next job application on the same site, the next record in the same form) takes seconds. Pass start_url for the new page and variables for the values that change; save reports the detected variables. A run stops at the first step it cannot find unambiguously or verify, and says which steps are done and which remain; finish that step yourself, then run again with from_step. The same review and authority apply to a replayed submit as to one you click yourself: run only a flow whose steps the user's request covers.
Inputs: action (required), name, tab_id, flow_id, +4 more.
browser_loginA
Sign in on a tab with the user's saved login for its site (saved with ascended-browser login add). Open the site's sign-in page first; this finds the username, password and one-time-code fields and types the saved values into them. You never see the values: they read as [redacted] in every result and are masked in screenshots. account_hint picks one account when several are saved for the site. submit=true also presses the form's sign-in button. After submission, navigation, or an authentication change, the result includes the resulting page snapshot; use it directly instead of immediately calling browser_observe. With no saved login for the site, ask the user to run ascended-browser login add <site>, or ascended-browser signin <url> to sign in by hand.
Inputs: tab_id (required), submit, account_hint.
browser_observeA
Observe a live tab and return generation-scoped element refs, on-screen controls first, current viewport content_blocks and measured scroll_containers. Treat auth_state as page evidence for your next decision; a visible login form does not itself stop the run. diagnostics lists page errors and failed requests since your previous result. When the result says elements were not shown, narrow the view instead of reading the DOM with browser_evaluate: query finds controls by their words, within scopes to a region, frame or element, and cursor continues where the last response stopped. Every ref returned is valid for browser_act.
Inputs: tab_id (required), query, cursor, filter, +1 more.
browser_openA
Wake the workspace and open or navigate your current browser tab. Pass either url or a bounded urls list (maximum 5). To check several sites, open them in ONE call with urls: it opens independent tabs in the same authenticated browser context and returns one compact, ordered result per URL; that results list is the authoritative source for each tab_id. A URL that fails (DNS, block) is reported on its own row and the other tabs stay open. Batch results omit page bodies: next, call browser_extract/observe for every returned tab_id together in one response, since calls on different tabs run in parallel. Returns once the page has settled. By default it reuses your current actor-owned tab, including across a resumed task; set reuse=false only for a genuinely independent second tab (the result carries reused=true when reused). The single-URL result includes a settled page snapshot; use it directly instead of immediately calling browser_observe. A page snapshot with login_available names matching saved vault accounts and directs you to browser_login. A page snapshot with auth_state.state=login_form_visible is not a fatal blocker: follow the user's request and call browser_login when appropriate. Only a returned attention_required=true represents an explicit handoff. A blocked=true page result does not suspend the run: decide whether to take another route or tell the user plainly what could not be completed. For broad public discovery use web_search rather than navigating this tab to a search engine; browser search remains valid when explicitly requested or interaction/personalization matters.
Inputs: url, read, urls, reuse, +2 more.
browser_screenshotA
Take a picture of an agent-owned tab. This is a last resort, not a way to find or operate controls: browser_observe returns the refs browser_act needs, and a picture returns none. Use it only for what an observation cannot describe (canvas, charts, images, visual layout). Password and payment fields are masked. The result states the viewport size at capture; a person may resize the live window, so trust it over sizes you saw earlier. state captures a ref's :hover/:focus styling; compare_with diffs against an earlier picture or another tab and boxes what changed. To check a page you are building against an original, open both and take one with compare_with='tab:': one picture of both.
Inputs: tab_id (required), ref, label, scope, +2 more.
browser_tabsA
List, close, or sleep workspace tabs. Closing takes tab_id for one tab or tab_ids for several in a single call (at most 20); each tab's outcome is reported separately, so one unknown id does not strand the rest.
Inputs: action (required), tab_id (required), tab_ids.
browser_viewportA
Check a responsive layout in the current agent-owned tab. action=set with preset phone (390x844), tablet (768x1024) or desktop (1365x768), or width and height in CSS pixels, resizes the real browser window so the page reflows as it would on that screen (Linux; elsewhere the window keeps its size). action=restore returns to the launch size and clears emulation; call it when the check is done. action=get reads the current size. action=emulate sets color_scheme (light or dark), reduced_motion, forced_colors or offline. A successful set or restore includes a fresh page snapshot; earlier element positions are stale after a resize, so use the new refs.
Inputs: action (required), tab_id (required), clear, width, +6 more.
wait_for_bot_wallA
Wait out a bot wall on a tab, then attempt to solve it if it does not clear on its own. Polls the tab while the wall is auto-verifying (e.g. a Cloudflare 'Just a moment…' check that clears itself). If it becomes a user-required challenge it runs the configured solver, and if that fails it returns a structured verdict. Also call it before submitting a form that carries an embedded Turnstile, reCAPTCHA or hCaptcha checkbox: it waits for the widget to pass, presses the checkbox if needed, and reports whether a token was issued (image puzzles are never solved). When the page is required for the user's goal, stop and tell them to solve it (or hand off if you are a browser sub-agent); otherwise continue to the next task.
Inputs: tab_id (required), max_wait_ms, apply_solver, poll_interval_ms.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Tools cover distinct phases (navigate, observe, extract, act, screenshot, evaluate), and the descriptions explicitly cross-reference each other to route the agent (e.g. extract over evaluate for text, observe over screenshot for controls). The observe/extract/evaluate/screenshot cluster still has inherent overlap that only careful reading of the long descriptions resolves, so it is not perfectly self-evident.
Ten of eleven tools consistently use the browser_<verb>_<noun> snake_case pattern (browser_open, browser_extract, browser_act, browser_tabs). wait_for_bot_wall is the sole outlier with no prefix, though it is still readable and snake_case.
Eleven tools is well within the ideal range and each maps to a genuine browser-automation capability (navigation, login, observation, extraction, action, viewport, replay, screenshots, tab management, bot walls). No tool appears redundant or decorative.
The lifecycle is broadly covered: open, observe, extract, act, save/replay flows, screenshots, tabs, and viewport/auth emulation. Minor gaps remain around JS dialog handling, downloads, and cookie/storage inspection, which agents would occasionally need.
Maintenance
Related MCP Connectors
Let your AI agent operate any website through a real, logged-in browser session.
Hosted browser for agents: open pages, search the web, extract data, read PDFs and take screenshots.
AI-powered browser automation — navigate, click, fill forms, and extract data from any website.
Control a real browser from AI agents: navigate, click, type, screenshot, read the page.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables AI agents to fully control a browser for web automation, including navigation, clicking, typing, scrolling, screenshots, and DOM inspection, with session persistence and anti-bot bypass.4036 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to search the web, read and extract content from webpages, fetch JSON from REST APIs, and collect links while bypassing anti-bot protections.35 npmISC
- FlicenseNot gradedqualityBmaintenanceEnables AI assistants to browse websites, extract information, fill forms, interact with pages, and execute multi-step web tasks autonomously.-
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to control a real browser through intent-based tools—reading pages, filling forms, clicking, and replaying self-healing recipes—while returning only concise answers instead of the DOM.11 npm1MIT