Skip to main content
Glama

browser-control-mcp

Discord

Browser Control MCP lets an AI agent control and debug real browsers at runtime: breakpoints, pause on load, call frames, evaluation in a paused frame, stepping and script search on Chrome (CDP) and Firefox (WebDriver BiDi + Firefox RDP), plus navigation, DOM, input, screenshots, console and network capture.

It is the successor of chrome-debug-mcp (it starts from a copy of its code) and complements Playwright MCP or chrome-devtools-mcp with runtime JavaScript debugging on both browsers.

Status: release candidate (1.0.0-rc.1). Feature-complete for 1.0: until 1.0.0 only bugs are fixed, and tools, arguments and replies do not change unless a fix needs it. Differences between Chrome and Firefox are in Limitations and TODO; what has not been verified, in Untested. Please report problems in the issues, as Reporting issues says.

💬 Questions, ideas or feedback: join us on Discord, where every release is announced in #announcements.

Comparison with Playwright MCP and chrome-devtools-mcp

Measured on 2026-11-08 with browser-control-mcp 0.13.0-beta.23 built from the current sources, @playwright/mcp 0.0.84 and chrome-devtools-mcp 1.12.0, driven by the same stdio client through the same tasks on Chrome 156.0.8078.47 (headless, Linux) with tests/compare/bench.py. Every outcome was checked in the page, not taken from the reply. Tokens are estimated as characters / 4 for every server. The HTTP authentication row comes from the tests/compare scenarios. The rows on secrets, top-level await, credential headers and WebSockets were checked on 2026-11-21, and the mocks row on 2026-11-22, in the sources and by running them, against @playwright/mcp 0.0.86 and chrome-devtools-mcp 1.13.0; what browser-control promises there, and what it does not, is in Scope of the convenience features.

What each one can do

browser-control-mcp

Playwright MCP

chrome-devtools-mcp

JavaScript debugger (breakpoints, call frames, stepping, script search)

✓ Chrome and Firefox (pause on load: Chrome; --tool-groups debug)

✗

✗

Firefox

✓ next to Chrome, same tools

✓ one browser per server

✗

Several browsers and instances at once

✓

✗

✗

Selectors

CSS, snapshot refs, host >>> inner into shadow roots and iframes

CSS, snapshot refs

snapshot refs only

Frames of another origin (payment forms, embedded editors)

✓ in the snapshot, refs f2e5 for every input tool, their console and network in the tab's logs

✓ refs f1e5

✗

Snapshot of a long page

bounded at 50 000 characters, find_in_snapshot searches the rest

unbounded

unbounded

Waits for the page to react after an action

✓ ~50 ms when nothing reacts

✓ ~500 ms

✓ ~200 ms

Clicking a covered or hidden element

fails at once, naming the overlay

fails after a 5 s timeout

reports success (the overlay gets the click)

Page behind HTTP authentication (401)

fails at once naming its scheme and realm and how to log in (credentials in the URL), on Chrome and Firefox

fails with Chrome's invalid-credentials network error

reports success, with the same error in the text

Mock requests, offline mode

✓

✓

✓ with --categoryNetworkMocks: a local file (status 200) or another URL's response; offline

PDF

✓ file or inline

✓ file

✗

Cookies and web storage

✓ values hidden unless asked

✓ values shown

✗

Secrets masked in output (--secrets)

✓ a whole value, as written and JSON-, HTML- or URL-encoded (up to six layers)

✓ the literal text only: a value with " or & shows once the reply is JSON-, HTML- or URL-encoded

✗

await at the top level of evaluated code

✓ statements as in a console (const r = await fetch(u); r.status), the last expression's value returned

✗ takes a function (async () => { ... })

✗ takes a function; format: "script" runs statements, without await

Credential headers in a request's details (Authorization, Cookie, X-Api-Key...)

hidden by default: only the standard headers on an allowlist of exact names show their value

shown

shown; --redactNetworkHeaders (off by default) hides them the same way

WebSocket frames and closes

✓ per connection: the document's, its frames', its workers' and its popups' (a Firefox popup's from when the debugger attaches)

✗ not listed

✗ not listed

Performance

vitals + insights (INP, LCP breakdown and discovery, layout shifts, render-blocking, long scripts, DOM size, images, third parties; on Chrome: forced reflows, unused JS/CSS, trace export .json/.gz, DOM/listener counters after GC); CPU and network throttling on Chrome

trace file

trace + insights; CPU and network throttling

Page audit (accessibility, SEO, best practices)

✓ audit_page, on Chrome and Firefox: failing elements with snapshot refs, no bundle; lighthouse_report: Lighthouse-style 0-100 scores of a cold mobile or desktop load (performance from a trace, with Speed Index, on Chrome) and the points each failing check costs

✗

Lighthouse, Chrome only: scores, failing elements with selectors, reports saved to disk

Heap snapshots, CSS styles, screencast

✗

video, tracing

✓

Generates Playwright test code

✗

✓

✗

Telemetry

none

none found

usage statistics on by default; traced URLs sent to CrUX

Single native binary (no Node.js)

✓

✗

✗

Measured

Task

browser-control-mcp

Playwright MCP

chrome-devtools-mcp

Tool list in context, default tools

6 668 tokens (8 495 with the debugger, --tool-groups debug)

5 530 tokens

7 774 tokens

Tool list in context, every opt-in tool on

13 447 tokens

12 291 tokens

not measured (optional categories)

Snapshot of Hacker News

4 584 tokens

12 112 tokens

6 918 tokens

Snapshot of Wikipedia "Web browser"

12 569 tokens (cut, searchable)

34 316 tokens

27 648 tokens

Snapshot of MDN <input>

12 565 tokens (cut, searchable)

158 037 tokens

77 206 tokens

Log in step by step (8 calls)

296 tokens, 0.6 s

626 tokens, 1.2 s

345 tokens, 1.4 s

Log in with fill_form (5 calls)

319 tokens, 0.5 s

433 tokens, 0.7 s

326 tokens, 0.8 s

Click, median

56 ms

516 ms

235 ms

Evaluate JavaScript, median

0 ms

504 ms

204 ms

Navigate (local page), median

46 ms

62 ms

117 ms

Full-page screenshot of a 31 700 px page

cut at 16 384 px, with a note

0.6 MB image in the reply, also saved to a file

saved to a file, with a warning that content past 16 384 px may repeat or be corrupted

Navigation to an unknown host

error

error

success with the error in the text

Navigate, then read the console (log, warning, errors)

218 tokens (keeps the same site's earlier messages, here a favicon 404)

190 tokens

97 tokens

Navigate, then read the network log (3 requests)

193 tokens (also lists the documents of the 2 pages before)

115 tokens

87 tokens

Related MCP server: js-reverse-mcp

Advantages of a native Rust binary

browser-control-mcp is one compiled program; Playwright MCP and chrome-devtools-mcp run on Node.js. Measured on 2026-11-22 with tests/compare/footprint.py (median of 5 runs, Linux, Chrome headless): browser-control-mcp 1.0.0-rc.1, @playwright/mcp 0.0.86 and chrome-devtools-mcp 1.13.0, each started with npx as its README shows, and with node directly.

browser-control-mcp

Playwright MCP

chrome-devtools-mcp

Needs at run time

nothing else

Node.js

Node.js

Installed

one 30 MB file (a 6.7 MB download on Linux x64)

19 MB of npm packages, plus Node.js

18 MB of npm packages, plus Node.js

Start, until it answers MCP initialize

4 ms

178 ms; 455 ms with npx

280 ms; 542 ms with npx

Memory of the server, idle (browser left out)

13 MB

117 MB

164 MB

Memory of the server after 4 navigations

23 MB

133 MB

167 MB

Extra process when started with npx

none

npm, 109 MB

npm, 108 MB

  • It starts at once. A client that starts a server for each session or each subagent waits 4 ms instead of about 0.2 to 0.5 s. The npx ...@latest command the other READMEs give also asks the npm registry for the latest version each time it starts (checked with npx --loglevel=http), and downloads it when there is a new one; browser-control runs what was installed, also offline.

  • It uses 6 to 12 times less memory. 13 to 23 MB against 117 to 167 MB (plus about 108 MB for npm under npx), so many agents, each with its own server, fit on one machine. The browsers themselves use the same memory whatever drives them.

  • Nothing else to install. No Node.js (its node binary alone is 150 MB in v26.13.0 on Linux), npm or node_modules, and no clash with the Node.js version a project pins: one file from Homebrew, npm (which downloads the binary), the GitHub release, the MSI or cargo install.

  • Work on each reply is cheap. --secrets masks a 100 000-character reply with 100 overlapping secrets in about 10 ms, and top-level await is found by a native JavaScript parser, in the server's own process.

  • A bug fails one call, not the session. unsafe code is denied, and unwrap, expect and panic! are lint errors outside tests: an unexpected case comes back as a tool error, and the agent's session goes on.

What it does not change: the browser's own work. Launching Chrome and loading a page take the same time whatever drives it (the first navigation, which launches Chrome, took 195 to 267 ms with the three servers). The faster clicks and evaluations in Measured come mostly from how long each server waits after an action for the page to react (about 50 ms here when nothing reacts, 500 ms and 200 ms in the others), not from the language.

Supported browsers

Browser

Protocol

Validated with

Chrome / Chromium

Chrome DevTools Protocol

Google Chrome 156.0.8078.47 (Linux)

Firefox

WebDriver BiDi, plus the Firefox Remote Debugging Protocol (RDP) for the JavaScript debugger

Firefox 159.0 (Linux, snap)

The default browser is Chrome. Every instance runs one browser for its whole life: start the server with --browser firefox, or pass "browser": "firefox" to open_instance. If Chrome is not installed but Firefox is, the launch error says so and tells the agent to ask you before switching.

Tool groups

Every tool listed costs the agent context on every turn, so niche and risky tools are off by default and listed only with --tool-groups:

Group

Tools

Why it is opt-in

debug

set_breakpoint, remove_breakpoint, step_over, step_into, step_out, call_stack, evaluate_on_call_frame, pause_on_exceptions, search_scripts, pause_on_load

the JavaScript debugger: 10 tools only a debugging session needs (resume is always listed, so a page that paused itself can go on)

storage

cookies, web_storage

reads and changes session tokens

files

upload_file, save_pdf, record_video

reads and writes files of the machine

raw

send_cdp_command, send_bidi_command, send_rdp_request, get_custom_events

anything the protocol allows

perf

get_performance_metrics, profile_page_performance, audit_page, lighthouse_report

niche

emulation

emulate

niche

network

mock_route, list_routes, remove_route, set_offline

changes what the page receives

--tool-groups all lists every group. The page, input and observation tools and resume are always listed (31 tools), plus enable_proxy_auth with --proxy-server and the WebMCP tools with --enable-webmcp. A tool of a group that is off fails naming the flag. The list is fixed for the server's life: it never changes during a session, so clients can cache it. Tools that only read (snapshot, find_in_snapshot, inspect_dom, capture_screenshot, wait_for, audit_page, call_stack, search_scripts, get_css_styles, get_performance_metrics, the list_* and WebMCP list/get tools) carry the MCP annotation readOnlyHint (not those whose clear removes what they read), and those whose effect is easy to undo (open_tab, emulate, set_breakpoint, mock_route...) destructiveHint: false; the others keep the protocol's defaults.

Feature matrix

✓ supported, ✗ not available (the tool answers a capability error naming the tool, the browser and the reason; nothing is sent to the browser), partial: see the note.

Tool

Chrome

Firefox

Notes

open_instance

✓

partial

features, copy_cookies and source_profile are Chrome only

close_instance

✓

✓

list_instances

✓

✓

each instance reports its browser and capabilities

restart_browser

✓

✓

was restart_chrome; refused on a Chrome already running on the port (attached, not launched by the server); the new browser's first page is registered as a tab

stop_browser

✓

✓

was stop_chrome; on an attached Chrome or Firefox it only disconnects (Firefox: ends the session), the browser keeps running and the reply says so

open_tab

✓

✓

the new tab becomes the active one, in front; an instance's start tab still blank and unlabelled, when it is the only tab, is used, once, instead of opening a second tab beside it (the next open_tab opens its own; on Chrome, never after the session reconnected to the browser, as it does once the last tab was closed); with url, that page is the tab's first history entry (on Chrome, history.length still counts the blank creation page when the page adds entries while loading: pushState, a script redirect)

close_tab

✓

✓

tab_id defaults to the active tab; the most recently active open tab (else the newest) becomes active and is brought to the front; it answers once the browser no longer lists the page (Chrome: at most 2 s), so the next tool never reaches the closed one

list_tabs

✓

✓

tabs in the order they were opened (tab-2 before tab-10); like any other tool it launches or connects to the instance's browser, so a fresh instance lists its start tab (about:blank)

list_downloads

✓

✓

the files the instance's pages downloaded, oldest first (id, url, file_name, path once complete, state in_progress / completed / canceled, sizes, tab_id), and the directory they are saved in; an input action that starts a download says where the file went. Chrome: saved under its guid (Browser.setDownloadBehavior allowAndName), then given its name without replacing a file (data (1).csv); Firefox: browser.setDownloadBehavior, numbered by Firefox (data(1).csv), sizes read from the saved file

switch_tab

✓

✓

navigate

✓

✓

url must be absolute (a javascript: URL is refused, pointing to evaluate_js; localhost:8080 or example.com:8080 without a scheme suggests http://); history: "back" or "forward" instead of url moves one entry in the tab's history and waits for the page to load (also when it comes from the back-forward cache, which fires no load); at either end it fails without moving (the page a tab was created with, blank or the browser's new-tab page for the tab the instance starts with, is not an entry to go back to; on Chrome history.length still counts it); a URL the browser saves instead of opening (a download: Content-Disposition: attachment, or a type such as CSV) fails saying so, and the tab stays where it was; a page behind HTTP authentication (401) fails at once naming its scheme and realm and how to log in (credentials in the URL, http://user:password@host/path, which the browser keeps for the session); a page that pauses at a breakpoint or opens a dialog while loading fails at once naming it (see resume, handle_dialog)

reload

✓

✓

a pause, a dialog or HTTP authentication while loading fails at once, as with navigate

scroll

✓

✓

reports the window positions before and after; wheel: true dispatches a real mouse wheel event instead (x/y pixels, default 100 down) at selector or the viewport's centre, for a canvas or map listening to wheel (Chrome Input.dispatchMouseEvent mouseWheel, Firefox a BiDi wheel action)

emulate

✓

partial

emulation group; width/height, device_scale_factor, mobile (touch), color_scheme, reduced_motion, forced_colors, media (print), user_agent, locale, timezone (checked by the page's Intl first), geolocation (the page is granted the permission to read it), cpu_throttling (1–20×), cpu_performance_tier (low, mid, high, ultra, unknown, none to remove: what navigator.cpuPerformance reports, Emulation.setCPUPerformanceOverride), network_throttling (slow-3g, fast-3g, 4g, none), reset; each call adds to the earlier ones; answers what the page now sees (with the position it reads and the active throttling; a mobile viewport the page lays out wider than asked, a page without a viewport meta tag at a phone's 980 px, comes with a note saying why); Firefox: no mobile, media, throttling or cpu_performance_tier options (BiDi has no media, touch or throttling emulation yet, and Firefox no navigator.cpuPerformance; they fail naming them)

wait_for

✓

✓

waits (checking every 100 ms, at most 30 s) until a visible text appears or is gone, a selector is visible / hidden / attached / detached, or the URL contains a text; a dialog or debugger pause ends the wait at once, as does the tab closing (on Firefox also the instance closing)

inspect_dom

✓

✓

includes open shadow roots and same-origin iframes (cross-origin ones are noted); at most 100 000 characters without query (cut in the page)

get_css_styles

✓

✓

why an element looks as it does: the rules that match it, highest priority first (the style attribute as element.style, then the rules), each with selector, origin (author, inline-style, user-agent), stylesheet (the sheet's URL; the page's for an inline <style>), 0-based line_number and column_number in that stylesheet, at_rules (@media, @container with its container's name, @layer, @supports) and its declarations marked important, invalid or overridden; pseudo_elements; with include_inherited the ancestors' rules (distance 1 is the parent); computed values of the declared properties (or of properties, which also limits the declarations; a shorthand matches its longhands); user-agent rules only with include_user_agent; at most max_rules rules (30). Chrome: the CSS domain, in the frame the selector names. Firefox: its inspector over the debugger port (refs, open shadow roots and same-origin frames work); Firefox names a rule's sheet only by an id, so the page finds the sheet holding a rule with the same selector and declarations (the page's URL when none is found)

snapshot

✓

✓

outline of the page: role, name, states, value and a ref (e12) per element, through open shadow roots and same-origin iframes, and on Chrome closed shadow roots too (pages up to 20 000 elements; their elements are reached by ref, not by >>>); frames of another origin are read too (at most 20, 5 deep), their iframe marked [frame=f2] and their refs prefixed (f2e5), and selector: "f2" outlines one; tables without headers (th, thead, caption) are layout and leave only their content, and a cell is named by its text only when it holds nothing else; comboboxes, spinbuttons and sliders built with ARIA show their value (the field's text, aria-valuetext or aria-valuenow, the option a button-like combobox shows), progress bars and meters theirs (40/100), and a <details> summary `[expanded=true

find_in_snapshot

✓

✓

text (case-insensitive) or regex over the whole outline; matching lines under their ancestors, at most 20

record_video

✓

✗

files group; Chrome 156 or later (Page.startScreenRecording; WebDriver BiDi has no video recording); action: "start" (optional frame_rate 1–60, max_width, max_height), then action: "stop" writes an MP4 (AV1) to path (an absolute .mp4 under the upload roots) or to a new file in the temp directory and returns {path, bytes, duration_s}; at most 256 MB; a hidden tab draws no frames

save_pdf

✓

✓

files group; prints the tab as the browser's print does (landscape, print_background, scale 0.1–2, page_ranges like 1-3, 5); with path (an absolute .pdf under the upload roots) writes the file and answers {path, bytes, pages}, else returns the PDF as an embedded application/pdf resource (at most 5 MB); Chrome Page.printToPDF, Firefox browsingContext.print

capture_screenshot

✓

✓

format png, jpeg (or jpg) or webp; full_page at most 16 384 px per side (a text note says when cut); selector captures one element (CSS, host >>> inner or a snapshot ref), scrolled into view for the capture and the page's scroll put back after it, whole even when taller than the viewport, cut to the page when partly outside it (with a note); a hidden or zero-size element is refused before anything scrolls, and one still outside the page once scrolled to is refused with the scroll put back; on Chrome a minimized window is restored for the capture and minimized again, and a tab in the background of its window (hidden) is refused, naming switch_tab

click_element

✓

✓

scrolls the element into view; button (left/right/middle), click_count (2 = double click) and modifiers; fails without clicking when it is hidden, covered (its own label on top does not count: styled checkboxes and switches are clicked through it; a covered element first gets the mouse, so controls shown only on hover are revealed and clicked) or a disabled control, whose handler would never run; an element a CSS selector does not find yet, or a disabled control, is checked again for up to 2 s, as pages add elements and enable buttons a moment after the previous action (a ref that names nothing, a hidden or a covered element fail at once); host >>> inner selectors reach open shadow roots and same-origin iframes (also in fill_input, scroll, wait_for); a dialog or debugger pause the click causes is noted in a successful reply ({dialog} or {paused, location}), also when its handler blocks the page after an await or a timer, while the page is watched to settle

fill_input

✓

✓

picks <select> options (on a <select multiple>, exactly the ones named one per line; an unknown one changes nothing); sets date, time, datetime-local, month, week, range and color inputs to the text in their own format (2026-10-31, 13:45, 72, #ff0000), firing input and change, noting a value the input adjusted (a range snaps to its step) and failing, without changing it, on a malformed one; fails without typing on elements that cannot take the text; append: true types after the content instead of replacing it (a number or email field, which has no caret, is retyped whole); an editor of its own (an element with an EditContext or a focusable textbox role, or the hidden input of a code editor such as Monaco or Ace) gets the keys a user presses: a click on the editor when its input has no visible box, Control+A (Command+A on macOS) or Control+End, then the text, and the reply says its content could not be checked; in a contenteditable element (including rich text editors such as Slate, Lexical, ProseMirror or CodeMirror 6) it selects the content (a range, then Control+A as a user would) and types over it, so the editor records the edit; types key by key on both (key handlers run; newlines and tabs inserted as text), about 1 ms per character; change on leaving the field, or at the end when the window has no focus; when the page moves the focus to other fields while typing (a code split over several boxes), the reply says how many took the rest of the text, and a field that loses the focus to nothing fails; Chrome: when a field of a frame of another origin does not take the focus (on Chrome 158+ its embedder may deny it focus-without-user-activation), its <iframe> is focused from the page and the focus tried once more, and a focus the policy still refuses fails saying to click_element the field first

press_key

✓

✓

one key (a character, Enter, Tab, Escape, arrows, F1–F12...) with Control / Shift / Alt / Meta held (in modifiers, or written before the key as Control+a, Shift+Tab or ControlOrMeta+c: Meta on macOS, Control elsewhere), in selector (focused first, handed down from the page into a frame of another origin as fill_input does on Chrome) or the focused element; a shortcut types nothing

hover

✓

✓

moves the mouse over the element (scrolled into view; fails when hidden or covered)

drag

✓

✓

presses on from (checked like click_element), moves in steps to the centre of to (which must then be in the viewport) and releases: sortable lists, boards, sliders; HTML5 drag and drop is real on Chrome and simulated with script events on Firefox (its WebDriver input starts a native drag but never drops it), and the reply says so

fill_form

✓

✓

several fields in one call: text and <select> as fill_input, a checkbox or radio takes true/false and is clicked only when its state differs; stops at the first failing field naming what was done; never echoes values

upload_file

✓

✓

files group; sets the files of an <input type=file> (Chrome DOM.setFileInputFiles, Firefox input.setFiles); files must be under the upload roots (--upload-root, default the working and temp directories)

handle_dialog

✓

✓

accepts or dismisses the open alert / confirm / prompt / beforeunload dialog; accepting a beforeunload waits (at most 5 s) for the navigation it allowed and names the URL reached; accepting a prompt without prompt_text answers its default, as a user pressing OK does

evaluate_js

✓

✓

await at the top level (const r = await fetch(u); r.json(), also inside a template's ${...}), as in a console, returning the last expression statement's value (trailing comments ignored; the expression is parsed with a JavaScript parser, so statements end where the browser ends them; an expression over 64 KB, or one that is not JavaScript, is not parsed: it runs once as written, as a plain script, and the browser's error is the answer, for long code with a note on the limit); an error in the code (syntax, runtime, a rejected promise) is returned as the browser reports it; value at most 100 000 characters (truncated: true); a value without a JSON form gets a bounded preview, the same on both browsers (preview: true: a Map as [key, value] pairs, a Set or a typed array as its items, an Error as {name, message, stack}, "[Circular]" for a cycle, "[Thrown: message]" for a getter that throws; description names it: Map(2), Uint8Array(3), TypeError: bad); symbols and functions are described (a function by its source); an exception's line and column are given when they are in the expression; user_gesture: true runs the expression as if the user had just interacted, so it can call APIs that need it (requestFullscreen(), navigator.clipboard.writeText(), window.open() past the popup blocker; off by default: the page gets that power, and --local does not check the pages it opens); Firefox before 160 also clears the activation an earlier click_element gave whenever the server evaluates script; Chrome stops a script after 8 s, Firefox cannot (a looping tab is closed with close_tab)

cookies

✓

✓

storage group; get / set / delete: the cookies sent to the page (or url; a cookie's path matches whole segments, /app is not sent to /application) or of a domain; values hidden unless show_values: true; a cookie without SameSite has same_site: null (Chrome Network.*Cookie*, Firefox BiDi storage.* in the tab's partition)

web_storage

✓

✓

storage group; get / set / delete / clear on the page's localStorage or sessionStorage; values hidden unless show_values: true

get_console_logs

✓

✓

one line per message, oldest first: [level] text @ url:line (lines from 1), objects and arrays previewed as the console shows them ({n: 1}, [1, 2, 3]), repeats in a row folded ([x3]), uncaught errors marked with up to 5 stack lines indented (an unhandled rejection Uncaught (in promise) …; Firefox: with its debugger port); on Chrome, an uncaught error's cause chain follows it, one Caused by: … line per link (an error's stack, up to 5 lines, or a short preview of another value; at most 10 links, a loop ends with [Circular]; cause is read without running a getter, which shows (...)), read from the page as the error comes and waited for up to 1 s by get_console_logs (Firefox, and console.error(error), show the error without its causes), console.count and the timers with their count and time, and Firefox's own messages (a rejected cookie, a CSP report) not marked uncaught; include_details: true gives the JSON with every field; a message keeps at most 10 000 characters; Firefox: page errors, CSS warnings and platform messages need the debugger port

get_issues

✓

partial

the problems the browser diagnosed that the console hides or words vaguely, one line each, oldest first: [code] title: summary @ url [xN] (a cookie blocked or warned and why, a CORS or Content-Security-Policy block, mixed content, a deprecated feature...); code filters, include_details gives the browser's details, clear removes what was returned. Chrome: its DevTools Issues panel (Audits domain, every issue code, in the tab and its frames of another origin), cleared when the tab moves to another site; the common codes and form problems have a title, N counts distinct reports (Chrome sends some twice with the same details: counted once), and the elements an issue of the tab is about follow its line as selector [ref=eN] (at most 10; in include_details, elements with ref, selector and opening tag). Firefox: no Issues panel; its security console messages read as CookieIssue, ContentSecurityPolicyIssue, MixedContentIssue, CorsIssue or SecurityIssue, and its deprecation warnings as DeprecationIssue (they need the debugger port)

get_network_logs

✓

✓

the tab's requests, its frames' and its dedicated workers', a popup's from its first (Chrome pauses each popup until its requests are recorded; on Firefox a popup's WebSocket frames and closes are recorded from the moment the debugger is attached to it, some milliseconds after it opens: Firefox cannot pause a new tab, so the frames of a socket opened at once, or a socket that opens and ends at once, are not listed); one line per request, oldest first (id METHOD url => status [type], or failed: <reason> / pending; a redirected request says (after N redirects from <first URL>), and url_filter matches any hop; a CORS block says blocked by CORS: <reason>; a request the page canceled after its response, such as a closed EventSource, keeps its status with canceled by the page), then one per WebSocket frame (payload preview) and, after a connection's frames (also when it has none), id closed <url> once it closed or id failed <url>: <error> after a frame error, with Firefox's close code and reason (: code 1000 bye; Chrome gives none, and reports no close for a connection the page left open when it navigated away: it is closed <url>: the page navigated away, nor for a socket of a frame of another origin when the frame goes: it is closed <url>: the frame was removed or navigated away (also when the frame navigates within its origin); not listed with ws_content_filter; clear forgets a closed connection with no frame left; the 100 newest connections of a tab are kept, and the frames of an older one, forgotten, are dropped with it, later ones too); request_id shows one request's headers and body, include_details: true every request's as JSON (a binary body has response_body_encoding: "base64"; bodies at most 64 000 characters; a body over 2 MB is not fetched and response_body_omitted gives its size; redirects lists each hop with its status and location; a WebSocket payload keeps 64 000, payload_len is the whole; websocket_closes gives each ended connection's closed_at (Unix ms, when the server saw it), close_code, close_reason, was_clean and error, when set); the browser's own requests (chrome://, devtools://, data:, about:, extensions) are not logged; a note counts the responses with no body because they are still loading or the page never read them (an open stream; on Chrome, a fetch whose body the page did not consume); Firefox: WebSocket frames need the debugger port, a frame's sockets (same-origin too) are listed and, as Firefox reports no close for them, closed <url>: the frame was removed or navigated away once the frame goes, a tab the page opens (a popup) is watched as it opens (see above for what comes before), the sockets of a document that navigated to another site are closed <url>: the page navigated away when Firefox reports no close for them, the socket of a terminated dedicated worker is closed once both close frames are exchanged (Firefox reports no close for it; when its server never answers the close frame it stays listed open, as on both browsers a socket the page closed does until its connection ends), a socket that fails before it opens is listed under the id of the close frame it sent (or its handshake's request id) with its handshake's URL, and one whose handshake the server refused (or that failed) as closed <url>: the handshake was refused: HTTP 403 Forbidden (or the handshake failed: <error>), a fetch or XHR has the type fetch / xmlhttprequest and a beacon none (Firefox gives no type for it)

mock_route

✓

✓

network group; requests whose URL matches a glob (*, ?, \ escapes) get a mocked status, body (text, at most 1 MB), content_type and headers without reaching the network; the latest matching route wins; a response the browser refuses fails the request instead of leaving it pending, and list_routes shows the browser's error; at most 50 routes per tab, kept until remove_route or the tab closes (Chrome Fetch, not while enable_proxy_auth is active; Firefox a network intercept)

list_routes

✓

✓

network group; the tab's routes with the requests each matched (hits), and, once the browser refused a route's response, how many of them failed (errors) and the browser's last_error (at most 300 characters)

remove_route

✓

✓

network group; one route by id, or all

set_offline

✓

✓

network group; requests fail as without a network and navigator.onLine is false, until set back (Chrome Network.emulateNetworkConditions, Firefox emulation.setNetworkConditions); Chrome still answers mocked routes and serves what its HTTP cache holds, as an offline browser does; Firefox fails every request, mocked ones too (it accepts the mocked response, then fails the request), and set_offline and mock_route say so when both are on

get_custom_events

✓

✓

raw group; {events, total, truncated}, the newest limit events; clear removes the returned ones; params over 64 000 characters of JSON are replaced by {truncated, characters}; Firefox: events of the modules subscribed with send_bidi_command (also those the server handles, such as browsingContext.load; a tab opening or closing, or an event without a context, goes to the active tab) and the event packets of actors addressed with send_rdp_request (rdp.<type>, e.g. rdp.evaluationResult)

get_performance_metrics

✓

partial

perf group; Chrome's metrics sorted by name, with the live Documents, Nodes and JSEventListeners of Memory.getDOMCounters; collect_garbage: true collects garbage first (HeapProfiler.collectGarbage), so reads after repeating an action show what it leaked; Firefox: Nodes, Frames, Resources, TransferSize from the Web Performance APIs (no Performance domain) and no garbage collection (WebDriver BiDi has none), plus notes

profile_page_performance

✓

partial

perf group; on Chrome a trace in which nothing loaded (no action: "reload") gives the current page's FCP, LCP, DCL and Load from the Web Performance APIs, as Firefox does, with a note; save_path (Chrome only) writes the raw trace (.json or .json.gz, under the upload roots) for Chrome DevTools or Perfetto; insights: true adds what explains the numbers, read with the Web Performance APIs and the DOM (same JavaScript on both): the document's TTFB, server time and compression, the LCP element, its breakdown (TTFB, load delay, load, render delay) and image discovery (lazy_loaded, fetch_priority), Interaction to Next Paint (inp: duration, event, target and input/processing/presentation breakdown), layout-shift culprits, render-blocking requests, the slowest requests, the 5 longest animation frames observed in the profile window (long_frames: duration_ms, blocking_ms, script_ms, render_ms, style_and_layout_ms, and on Chrome 157+ style_ms, layout_ms, forced_style_ms; a part the browser does not report is left out, and the parts need not add up to duration_ms; a finding for a frame of 50 ms or more at least half spent on style and layout, unless forced_reflows already names them), the scripts of long animation frames (with forced_style_and_layout_ms), DOM size (nodes, max_depth, widest_element, max_children), oversized or unsized images, and third-party origins by duration and bytes (at most 5 each), plus findings from the web.dev and Lighthouse thresholds; on Chrome, forced_reflows from the trace (Layout/UpdateLayoutTree forced by a script, grouped by call site, a finding over 30 ms) and, with action: "reload", unused_code (unused_js_bytes, unused_css_bytes and the 5 files with most unused bytes, from the Profiler precise coverage and CSS rule usage of the reload; a finding over 50 KB; without a reload it is null: code run before the recording would count as unused); Firefox: FCP, LCP, DCL and Load; no trace (save_path fails), so total_blocking_time_ms and top_long_tasks are null, and its insights have no layout shifts, render-blocking requests, long frames, forced reflows or unused code (null, with notes)

audit_page

✓

✓

perf group; accessibility (images without alt, fields, buttons and links without a name, html lang, heading order, duplicate ids, broken aria-labelledby/aria-describedby, tabindex > 0, targets under 24×24 px too close to another, text contrast under WCAG AA), SEO (title, meta description, viewport, vague link text, uncrawlable links, canonical, noindex) and best practices (doctype and quirks mode, HTTPS, mixed content, distorted images, console errors); the same script on both browsers; each failing check lists its first 10 elements with a snapshot ref, a selector, its start tag and a detail (the contrast ratio, the size...), then the ids that passed or did not apply; categories narrows it; not checked: text over background images or gradients, iframes, closed shadow roots, response headers

lighthouse_report

✓

partial

perf group; a cold load of url (default: the tab's page, loaded again) from about:blank in Lighthouse's conditions: device: "mobile" (default: 412×823 at 1.75×, touch, CPU 4× slower, Slow 4G) or "desktop" (1350×940, no throttling), the cache bypassed, the user agent left alone, the tab's own emulation put back afterwards and the cache re-enabled (a note names any override Chrome refused to put back); scores 0-100 for performance, accessibility, seo and best_practices (categories narrows them) with Lighthouse's formula: its log-normal curves for FCP, LCP, TBT, CLS and Speed Index (from the trace's screenshots) with weights 10/25/30/25/10, and its audit weights for the audit_page checks plus http-status-code (1 for viewport and mixed-content, which it does not score, and 3 for duplicate-id, which flags any duplicate id; document-title and image-alt count in two categories; a check that did not apply is left out); metrics gives each value, score and the points it costs, failed each failing check with points_lost per category (costliest first) and its elements with snapshot refs, then passed and not_applicable ids, insights as profile_page_performance gives them (with the load's unused JS/CSS and forced reflows on Chrome), and notes; Chrome: about 5-15 s; Firefox: viewport and device pixel ratio only (no throttling, touch or trace), FCP and LCP from the Web Performance APIs, performance null with a note

set_breakpoint

✓

partial

debug group; condition pauses only when the expression is truthy; log makes a logpoint (its value goes to the console as logpoint <url>:<line>: <value>, and it never pauses; with condition, only when it holds), both as the breakpoint's condition; a url without a scheme (app.js, js/app.js) names the loaded script whose URL ends with it (several: refused, naming them); with none loaded, Chrome binds it to the first such script that loads (urlRegex) and Firefox refuses it; Firefox: by URL only (no script_id / script_hash)

remove_breakpoint

✓

✓

debug group

resume

✓

✓

always listed (a page can pause itself); on a page that is not paused: The debugger was not paused: nothing to resume. with {paused: false}

step_over

✓

✓

debug group

step_into

✓

✓

debug group; enters the call on the paused line (Chrome Debugger.stepInto, Firefox resumeLimit: step)

step_out

✓

✓

debug group; runs to the caller (Chrome Debugger.stepOut, Firefox resumeLimit: finish); paused: false when no caller stops

call_stack

✓

✓

debug group; the paused stack, innermost first (at most 50 frames): index, function_name, url, 0-based line_number and column_number, reason (breakpoint, step, exception...) and the exception thrown; Chrome also lists each paused frame's scopes (index, type: local, closure, block, script, global...; name) and async_callers (setTimeout, promises; recorded only while the tab is debugged); Firefox gives no scopes and no async callers

pause_on_exceptions

✓

✓

debug group; state: none, uncaught (and unhandled rejections) or all, per tab (Chrome Debugger.setPauseOnExceptions, Firefox thread configuration pauseOnExceptions)

evaluate_on_call_frame

✓

✓

debug group; frame_index (from call_stack) evaluates in a caller's frame; past the stack it fails naming its size; on Chrome 156 or later scope evaluates in an enclosing scope of the frame (as call_stack numbers them) to read a variable an inner one hides, and past the chain it fails naming its scopes (an older Chrome, or one whose version could not be read, refuses it); Firefox refuses scope (its debugger evaluates in the innermost scope only)

search_scripts

✓

✓

debug group; a long line's preview is 100 characters on each side of the match; inline scripts and modules included, the server's own evaluations left out (Chrome: an inline script the debugger no longer holds, released while its page sat in the back-forward cache, is found in the page's <script> elements, with scriptId: null, lineInScript and a note to reload before setting a breakpoint in it); debug answers {scripts, errors} as JSON; frames of another origin too (Chrome ids such as 2.17)

pause_on_load

✓

✗

debug group; TODO on Firefox, see Limitations and TODO

enable_proxy_auth

✓

partial

needs --proxy-server; a request the proxy rejects twice is cancelled; untested on Firefox against a real proxy

send_cdp_command

✓

✗

raw group; raw Chrome DevTools Protocol; refuses Network/Page/Runtime/Log/Debugger.disable and Browser.close; Fetch.enable comes with a note

send_bidi_command

✗

✓

raw group; raw WebDriver BiDi; refuses session.new, session.end, browser.close

send_rdp_request

✗

✓

raw group; raw Firefox RDP request to an actor (thread, console, root shortcuts); the event packets that actor sends afterwards go to get_custom_events (at most 16 actors watched)

webmcp_list_tools

✓

✗

needs --enable-webmcp; WebMCP is a Chrome testing feature; every annotation Chrome reports is listed (readOnly, consequential, untrustedContent, debugging, autosubmit, newer ones as they are); compact JSON {frameId, tools} (frameId once when the tools share it), without empty required or false annotations

webmcp_invoke_tool

✓

✗

needs --enable-webmcp; frameId optional when one frame registers the tool; waits timeout_ms (default 10 000, at most 60 000) for the answer, then says how to poll or cancel it; a tool answering in MCP shape ({content, isError}) gives its own text and image blocks, and its isError makes the reply an error; other output comes as JSON; the output of an untrustedContent tool comes with a note to treat it as data

webmcp_get_invocation

✓

✗

needs --enable-webmcp; a pending invocation whose page navigated away carries a note

webmcp_list_invocations

✓

✗

needs --enable-webmcp; status in any case

webmcp_cancel_invocation

✓

✗

needs --enable-webmcp; cancels a pending invocation (WebMCP.cancelInvocation); one Chrome no longer knows (its page is gone) is marked Canceled

After click_element, hover, drag, fill_input, fill_form and press_key the server waits for the page to settle before answering: until its DOM stays unchanged for 50 ms (style changes, often animations, aside) and the requests the action started finished, at most 1 s, on both browsers. An action nothing reacts to costs those 50 ms and keeps its reply; otherwise the reply adds The page reacted (the DOM changed, 1 request(s)) and settled after 134 ms., or says the page was still changing after 1 s. A click that navigates waits for the new page's requests. Use wait_for for anything slower (a timer, a long request). An action that opened tabs (a target=_blank link, window.open) says so: The action opened tab tab-3 (https://…): call switch_tab with its tab_id to act in it. An instance tracks at most 16 tabs: one opened beyond that has no tab_id, and the action says so (close tabs with close_tab to make room); the agent's tab stays in front. One during which a tab closed (a page calling window.close()) names it and the tab now active. So does one that downloaded a file (The action downloaded data.csv (8 bytes) to …), opened a file chooser (set its files with upload_file; Chrome intercepts file choosers, so none opens on screen) or changed the URL without loading a page (history.pushState, a #fragment). In a textarea or contenteditable, fill_input types a newline as the Enter key.

The JavaScript debugger tools on Firefox need its debugger (RDP) port: on by default for a launched Firefox, --firefox-rdp-port for an attached one. The same port gives Firefox's WebSocket frames and the console messages BiDi does not report (script errors with their file and line, cookie and security warnings, CSS warnings, platform messages), in the same shapes as Chrome. Each tab's debugger watches them: the session's first tabs are attached when the session starts and open_tab attaches its tab before loading the URL; a tab the page opened is attached by the first get_console_logs or get_network_logs on it. Firefox itself says which RDP tab shows a BiDi tab (its Remote Agent maps the BiDi context to the tab's browserId), so tabs on the same URL, several windows and error pages are told apart, and a tab is never activated or brought to the front to attach it. Frames are captured from the moment a tab is attached.

📦 Installation

Every method installs the same pre-compiled binaries published on each GitHub Release; a Rust toolchain is only needed for the Cargo and source routes. The npm package is a small wrapper whose postinstall fetches the pre-compiled binary for your platform from GitHub Releases: no compiling, no Rust toolchain. Install Chrome and/or Firefox yourself: the server launches them, it does not ship them (except the Docker image).

⚠️ Always use the scoped npm name @raultov/browser-control-mcp. The unscoped browser-control-mcp on npm is a different, unrelated project.

Prefer zero effort? The one-prompt route below lets your AI agent do all of it. Otherwise, methods are grouped by platform and ordered by popularity.

🤖 One-Prompt Install (any platform)

Paste this prompt into any AI coding agent's chat (Claude Code, opencode, Cursor, Codex CLI, Copilot, ...) and let it install the server and register it with every MCP-capable client it detects on your machine:

Install and set up the browser-control-mcp MCP server on this machine. Do not launch Chrome or Firefox yourself: the server launches and manages them.

1. Install the server binary with the first method that works on this OS:
   - Homebrew available (macOS/Linux): brew install raultov/tap/browser-control-mcp
   - Node.js >= 14 available (any OS): npm install -g @raultov/browser-control-mcp
   - macOS/Linux fallback: curl --proto '=https' --tlsv1.2 -LsSf https://github.com/raultov/browser-control-mcp/releases/latest/download/browser-control-mcp-installer.sh | sh
   - Windows fallback: download and run the .msi from https://github.com/raultov/browser-control-mcp/releases/latest
   Verify with: browser-control-mcp --version (add the install dir to PATH if it is not found).

2. Register the MCP server with every AI client you detect on this machine:
   - Claude Code: claude mcp add --scope user browser-control-mcp browser-control-mcp
   - opencode: merge into ~/.config/opencode/opencode.json —
     "mcp": { "browser-control-mcp": { "type": "local", "command": ["browser-control-mcp"] } }
   - Codex CLI: append to ~/.codex/config.toml —
     [mcp_servers.browser-control-mcp]
     command = "browser-control-mcp"
   - Any other MCP-capable client (Cursor, Windsurf, VS Code, ...): add it with its own MCP settings, command "browser-control-mcp" with no arguments.

3. Report what you installed and which clients you configured, and remind me to restart each client so the MCP server loads. Do not enable --user-profile or --allow-cookie-import unless I ask for them.

macOS

1. Homebrew, the natural option on macOS:

brew install raultov/tap/browser-control-mcp

The formula fetches the pre-compiled binary (Apple Silicon and Intel) from GitHub Releases, and brew upgrade keeps you current.

2. npm / npx, the MCP-client convention (requires Node.js >= 14):

npm install -g @raultov/browser-control-mcp   # installs the `browser-control-mcp` command
npx -y @raultov/browser-control-mcp           # ...or just run it once, nothing to install

3. Shell installer, a one-liner that installs to ~/.cargo/bin:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/raultov/browser-control-mcp/releases/latest/download/browser-control-mcp-installer.sh | sh

4. Cargo, if you already have Rust:

cargo install browser-control-mcp --version 1.0.0-rc.1   # compiles from crates.io
cargo binstall browser-control-mcp    # with cargo-binstall: fetches the pre-compiled binary, no compile

5. Manual download: the aarch64-apple-darwin or x86_64-apple-darwin .tar.xz archive from the Releases page.

Linux

1. npm / npx (requires Node.js >= 14):

npm install -g @raultov/browser-control-mcp   # installs the `browser-control-mcp` command
npx -y @raultov/browser-control-mcp           # ...or just run it once, nothing to install

2. Shell installer, a one-liner that installs to ~/.cargo/bin:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/raultov/browser-control-mcp/releases/latest/download/browser-control-mcp-installer.sh | sh

The Linux binaries require glibc >= 2.35 (Ubuntu 22.04+, Debian 12+, Fedora 36+).

3. Homebrew (Linuxbrew), if you already use Homebrew on Linux:

brew install raultov/tap/browser-control-mcp

4. Cargo, if you already have Rust:

cargo install browser-control-mcp --version 1.0.0-rc.1   # compiles from crates.io
cargo binstall browser-control-mcp    # with cargo-binstall: fetches the pre-compiled binary, no compile

5. Manual download: the x86_64-unknown-linux-gnu or aarch64-unknown-linux-gnu .tar.xz archive from the Releases page.

Windows

1. npm / npx (requires Node.js >= 14):

npm install -g @raultov/browser-control-mcp   # installs the `browser-control-mcp` command
npx -y @raultov/browser-control-mcp           # ...or just run it once, nothing to install

2. MSI installer, the native Windows experience: download browser-control-mcp-x86_64-pc-windows-msvc.msi from the Releases page and double-click it.

3. PowerShell installer, a one-liner:

powershell -ExecutionPolicy Bypass -c "irm https://github.com/raultov/browser-control-mcp/releases/latest/download/browser-control-mcp-installer.ps1 | iex"

4. Cargo, if you already have Rust:

cargo install browser-control-mcp --version 1.0.0-rc.1   # compiles from crates.io
cargo binstall browser-control-mcp    # with cargo-binstall: fetches the pre-compiled binary, no compile

5. Manual download: the x86_64-pc-windows-msvc .zip archive from the Releases page.

Docker (amd64)

docker build -t browser-control-mcp .
docker run -i --rm browser-control-mcp --headless   # Chrome and Firefox inside

From source

git clone https://github.com/raultov/browser-control-mcp && cd browser-control-mcp
make install   # release build copied to ~/.cargo/bin (or cargo install --path . --locked)

Browser discovery

CHROME_PATH, then google-chrome, chromium and the usual install paths; --firefox-path, then FIREFOX_PATH, then firefox and the usual install paths.

MCP client configuration

Universal JSON:

{
  "mcpServers": {
    "browser-control-mcp": { "command": "browser-control-mcp", "args": [] },
    "browser-control-firefox": {
      "command": "browser-control-mcp",
      "args": ["--browser", "firefox"]
    },
    "browser-control-docker": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "browser-control-mcp", "--headless"]
    }
  }
}

Claude Code:

claude mcp add browser-control-mcp browser-control-mcp
claude mcp add browser-control-firefox -- browser-control-mcp --browser firefox
claude mcp add browser-control-mcp -- npx -y @raultov/browser-control-mcp

To debug JavaScript, add --tool-groups debug (see Tool groups): claude mcp add browser-control-mcp -- browser-control-mcp --tool-groups debug.

Usage concepts

  • Instances. A default instance always exists and uses the --browser flag. open_instance with a label starts another one (its id is the label), with browser to pick Chrome or Firefox. Browsers are launched lazily, on the first tool that needs them, with an ephemeral profile.

  • Tabs. open_tab, list_tabs, switch_tab, close_tab. Every tool takes instance_id and tab_id; without them it targets the default instance and its active tab. The active tab is the one the browser shows: open_tab makes its new tab active, close_tab brings the next one to the front, and after a page opens or closes a tab (a target=_blank link, a popup, window.close()) the active tab is brought back to the front. Once the last tab is closed, a tool says to open one, and open_tab does. On Chrome a tab whose page crashed is refused at once, naming reload. Background tabs are hidden to their pages (no requestAnimationFrame, throttled timers). An argument a tool does not have fails the call before anything runs (a tabId typo answers "did you mean tab_id?"), so a typo never falls back to the active tab.

  • Same replies on both browsers. navigate and reload answer once the page fired load (at most 30 s, else with a note): a first line (Navigated to <final URL>. / Page reloaded.), then {"url": "<final URL, after redirects>", "tab_id": "tab-N", "browser": {...}}, where browser holds the protocol's ids (CDP frameId/loaderId, BiDi navigation), plus "status", the document's HTTP status, for http(s) pages (an error status, 400 and up, also adds a note; an error page with an empty body is reported the same way on both browsers). A URL the browser downloads fails with Navigation failed: the URL is a download...; the file is still saved (see list_downloads). open_tab answers {tab_id, target_id, url, label} with the final URL. A network error (unknown host, refused connection...) fails with Navigation failed: <browser's code> (<url>), e.g. net::ERR_NAME_NOT_RESOLVED on Chrome and NS_ERROR_UNKNOWN_HOST on Firefox; from open_tab the error names the tab, which stays open. evaluate_js answers {"value", "type", "subtype"?, "description"?}: type is JavaScript's typeof, subtype refines objects (array, null, node, date, map...), value is the JSON form and is null when there is none (functions, DOM nodes, symbols, NaN, bigints, maps...), description then says what it was (Chrome describes functions by their source, Firefox only as function). An object or array's value is what JSON.stringify gives, on both browsers (toJSON counts: a URL is its href; nested functions drop out), and an object that is not a plain one has its class in description (navigator: {"value": {}, "description": "Navigator"}). A thrown exception or a rejected promise fails with what was thrown and its 1-based line and column, e.g. ReferenceError: x is not defined (line 1, column 1). A value over 100 000 characters is not returned whole: a string keeps its first 100 000, an object or array is measured in the page and only described; the reply then carries "truncated": true.

  • Acting on elements. snapshot outlines the page, one line per element with a role, e.g. textbox "Username" [ref=e3], button "Sign in" [ref=e7], iframe [ref=e9] with the frame's elements under it; find_in_snapshot returns only the lines that match, under their ancestors. The selector of click_element, fill_input, scroll and wait_for takes such a ref, a CSS selector, or host >>> inner to reach into an open shadow root or a same-origin iframe (#checkout >>> #card-number, chainable). A frame of another origin (a payment form, an embedded editor) is read as well, through its own target on Chrome and its own browsing context on Firefox: its iframe line says [frame=f2] and its elements have refs such as f2e5, which every selector argument takes, as does f2 >>> css; the input tools then check and act in that frame (one call acts in one document: fill_form and drag refuse selectors of two frames). An element keeps its ref in later snapshots while it is in the page; refs end when the page navigates (a stale ref fails saying so). Roles and names are computed in the page, an approximation of the browser's accessibility tree that is the same on both browsers; password values never appear.

  • Per-tab state. Console logs, network traffic, breakpoints and custom events are kept per tab, in bounded buffers. A tab's console buffer (last 1000 messages) is cleared when the tab moves to another site (registrable domain from the Public Suffix List: www.knot.kz and docs.knot.kz are one site, a.github.io and b.github.io two) and kept across reloads and same-page navigations. get_console_logs answers {"messages": [...], "total", "truncated", "notes"?}: at most limit (default 200) of the most recent matching messages, oldest first; clear removes only the returned ones; a note says when a site change cleared messages. get_custom_events answers {"events", "total", "truncated"} the same way. On Chrome both log tools connect first, so on an attached browser the first call already sees the page's console messages (Chrome replays them; network requests sent before the connection are not captured, and the reply says so).

  • Firefox allows a single automation session. Each Firefox instance holds one WebDriver BiDi session shared by its tabs; close_instance, stop_browser and every server shutdown path end it, so the next run can attach again.

CLI flags

Flag

Default

Chrome

Firefox

--browser <chrome|firefox>

chrome

browser of the default instance

browser of the default instance

--local

off

navigation limited to local addresses

same

--headless

off

headless Chrome (also the default of open_instance's headless)

headless Firefox (same)

--window-size <W>x<H>

1920x1080

window of launched Chrome (--window-size)

window of launched Firefox (--width/--height)

--host <HOST>

127.0.0.1

debugging host

debugging host

--port <PORT>

none (launch)

without it the default instance launches a Chrome of its own on a free port (list_instances shows it); with it, it attaches to the Chrome already running on that port, or launches one there (a remote --host, or --user-profile, attach on 9222 when no port is given)

ignored (use --firefox-port)

--max-instances <N>

8

instance cap, the default instance included (its slot is held before its first use)

shared with Chrome

--enable-automation

off

shows the automation infobar

ignored; list_instances shows a warning

--user-profile

off

your default profile (no --user-data-dir)

only with --firefox-port (attach to your running Firefox)

--allow-cookie-import

off

exposes copy_cookies

capability error

--secrets <FILE>

none

dotenv file (NAME=value, at least 4 characters per value) whose values every tool result and error shows as <secret:NAME>; fill_input and fill_form type the value of a <secret:NAME>. Whole values only (see Scope of the convenience features and Security notes)

same

--tool-groups <GROUPS>

none

lists the opt-in tool groups, comma separated: debug, storage, files, raw, perf, emulation, network or all (see Tool groups)

same

--upload-root <DIR>

working + temp dir

directory upload_file may read files from and save_pdf may write PDFs to (repeatable; replaces the defaults)

same

--downloads-dir <DIR>

inside the instance's profile

each instance saves downloads in a folder of <DIR> named after its id (see Security notes; kept after the instance closes); without it, in a downloads folder of the instance's temporary profile (deleted with it), or a new folder in the system temp directory for an attached browser or --user-profile

same; snap Firefox can only write to non-hidden folders of $HOME (not ~/.local/...): it cancels the download otherwise

--enable-webmcp

off

WebMCP switches and webmcp_* tools

capability error

--proxy-server <URL>

none

proxy for every instance (host:port alone means http://host:port; a value that is not a proxy URL stops the server at start-up); exposes enable_proxy_auth

http:// and socks5:// proxies

--proxy-username <USER>

none

answers proxy (407) challenges

same (untested)

--proxy-password <PASS>

none

never logged

same

--firefox-path <PATH>

discovered

—

Firefox binary to launch

--firefox-port <PORT>

none (launch)

—

attach to a running Firefox's BiDi port

--firefox-rdp-port <PORT>

none

—

debugger port of the attached Firefox (needs --firefox-port)

--no-firefox-debugger

off

—

launch Firefox without its debugger port (no debugger tools)

Credentials written in a proxy URL (http://user:pass@host:port) never reach the browser's command line; enable_proxy_auth uses those of --proxy-server when neither its arguments nor --proxy-username/--proxy-password give them.

--proxy and --webmcp are aliases. To attach to your own Chrome, start it with --remote-debugging-port <port> and pass --port <port>. To attach to your own Firefox, start it with --remote-debugging-port <port> (and --start-debugger-server ws:<rdp> plus devtools.debugger.remote-enabled and devtools.chrome.enabled for the debugger), then pass --browser firefox --firefox-port <port> --firefox-rdp-port <rdp>.

Architecture

 MCP client (agent)
     │  JSON-RPC over stdio (tools/list, tools/call)
     ▼
 browser-control-mcp ── tool table: flag gate → capability check → per-browser handler
     │                                   │
     │ Chrome instance                   │ Firefox instance
     ▼                                   ▼
 cdp-browser-lite / cdp-lite         bidi-browser-lite / bidi-lite
 (launch, ports, profiles,           (launch, prefs, one BiDi session,
  CDP over WebSocket)                 RDP client for the debugger)
     │  CDP commands/events              │  BiDi commands/events   │  RDP packets
     ▼                                   ▼                         ▼
   Chrome                              Firefox ◄───────────────────┘

A tool call resolves the instance (instance_id, default default) and the tab (tab_id, default active), checks the instance can serve it, then runs the implementation for that instance's browser. Events are pumped into per-tab state: on Chrome, one listener per CDP domain and tab; on Firefox, one subscription per session, routed by browsing context id.

Debugging JavaScript

The debugger tools are listed with --tool-groups debug (or all): add it to the server's arguments in the MCP client configuration (resume is always listed, so a page that paused itself can go on). Chrome and Firefox take the same calls:

  1. navigate to the page (or open_tab).

  2. search_scripts with a needle to find the script URL and line.

  3. set_breakpoint with url and line_number (0-based).

  4. Trigger the code (click_element, evaluate_js with a setTimeout, a reload...). The page pauses. A click_element whose handler hits the breakpoint answers at once, as a success: the click happened, and the reply adds The page paused in the debugger at <url> line N, column M (0-based) (the URL when the browser gives it) and {"paused": true, "location": ...}. Any other call the pause leaves unfinished (evaluate_js, fill_input, navigate...) fails at once with that location.

  5. call_stack lists the paused frames and why the page paused; evaluate_on_call_frame reads locals of the paused frame (or of a caller, with frame_index); step_over moves one statement, step_into enters a call, step_out returns to the caller; resume continues. While paused, the input tools (click_element, hover, drag, fill_input, fill_form, press_key) fail at once naming the pause and do nothing: the page would handle their events only after resume. evaluate_js still answers while paused, in the page's global scope. A promise it returns cannot always settle meanwhile: Chrome reads a settled one and fails at once on a pending one; Firefox settles it when its microtasks can run.

  6. remove_breakpoint with the id set_breakpoint returned.

Both browsers answer the same replies, with 0-based lines everywhere:

Tool

Reply

set_breakpoint

{"breakpoint_id": "bp-N", "url", "line_number", "column_number", "resolved", "condition"?, "log"?}: where the browser bound it; resolved is false until a script with that URL loads, and the first line then says it is not bound yet

remove_breakpoint

{"removed": "bp-N"}; an unknown id fails listing the tab's ids

step_over, step_into, step_out, resume

{"paused", "location": {"url", "script_id"?, "line_number", "column_number"} | null}: where the thread stopped next (script_id on Chrome, for set_breakpoint) (step_over waits up to 2 s; resume reports a pause only if one follows within 250 ms)

evaluate_on_call_frame

the evaluate_js shape; an exception fails with Evaluation threw: <what was thrown>

call_stack

{"reason", "exception"?, "frames": [{"index", "function_name", "url", "line_number", "column_number", "scopes"?}], "async_callers"?}

pause_on_exceptions

{"pause_on_exceptions": "none" | "uncaught" | "all"}

Breakpoint ids are per tab and MCP-level (bp-1, bp-2...), like tab ids.

While a tab has no breakpoint, does not pause on exceptions (and, on Chrome, has no pending pause_on_load), the page's own debugger; statements do not pause it: the debugger is always attached, and anti-debugging pages loop on debugger; to freeze every tool. The first breakpoint, or pause_on_exceptions, turns them back on.

Chrome also offers pause_on_load: it reloads the tab and answers once the page paused before any of its scripts runs, at a debugger; statement it injects (browser-control-mcp://pause_on_load, reason pause_on_load in call_stack), so breakpoints can be set in the page's scripts before they run; resume continues the load. Firefox notes: breakpoints by URL only; without column_number the breakpoint binds to the first breakable column of the line, in whichever of the page's scripts with that URL has one (inline <script> blocks share the page's URL), and needs the script loaded; the debugger needs the RDP port.

Migration from chrome-debug-mcp

chrome-debug-mcp 1.5.6

browser-control-mcp

binary / crate chrome-debug-mcp

browser-control-mcp

npm @raultov/chrome-debug-mcp

@raultov/browser-control-mcp

tool restart_chrome

restart_browser

tool stop_chrome

stop_browser

replies printed as Rust Debug (WsResponse { .. })

prefix + pretty JSON of the reply

get_network_logs returned credential headers

<redacted> unless include_sensitive_headers: true

enable_proxy_auth answered every auth challenge

answers proxy (407) challenges only

All command-line flags are kept; --browser, --firefox-path, --firefox-port, --firefox-rdp-port and --no-firefox-debugger are new. In client configurations replace the command chrome-debug-mcp with browser-control-mcp (or the npm package name). The old tool names answer an error that names the new ones.

Migration from 0.1.x to 0.2.0

0.2.0 makes the replies the same on Chrome and Firefox; these changes are incompatible:

Tool

0.1.x

0.2.0

navigate, reload

Chrome: raw Page.navigate reply (frameId, loaderId, errorText) without waiting, {} on reload; Firefox: {navigation, url}

{url, tab_id, browser, status?, notes?} after load; url is the final URL; protocol ids under browser; status is the document's HTTP status

navigate, open_tab to an unreachable host

Chrome: success (errorText inside, or a chrome-error:// tab)

error Navigation failed: <code> (<url>); open_tab names the tab, which stays open

evaluate_js

Chrome: {"result": {type, value, ...}}; Firefox: the bare value

{value, type, subtype?, description?, preview?, truncated?}

set_breakpoint

Chrome: CDP id (1:3:0:http://…) and locations; Firefox: {breakpointId, url, lineNumber, columnNumber}

{breakpoint_id: "bp-N", url, line_number, column_number, resolved}

remove_breakpoint

Chrome: CDP id, reply {}

bp-N id, reply {removed}

step_over, resume

Chrome: text only; Firefox step_over: {paused, location: {line (1-based), column}}

{paused, location: {url, line_number, column_number} | null}, 0-based

evaluate_on_call_frame

Chrome: raw RemoteObject (exceptions as success); Firefox: bare value

the evaluate_js shape; exceptions are errors (Evaluation threw: ...)

get_custom_events

Found N custom events. Captured events: [...], the oldest events

{events, total, truncated}, the newest limit events; clear removes the returned ones

get_console_logs

a JSON array; clear emptied the whole buffer

{messages, total, truncated, notes?}, at most limit (200) messages; clear removes the returned ones; the buffer is cleared on cross-site navigation

Scope of the convenience features

Five things this server does go beyond passing the agent's request to the browser (see the comparison). Each is a convenience with a stated scope. Inside it, a failure is a bug; outside it, it is not.

  • evaluate_js runs the agent's code. A syntax error, a runtime error or a rejected promise is returned as the browser reports it, with its line and column. Top-level await works for code of up to 64 KB that parses as JavaScript: it runs inside an async function (so its var and function declarations are not globals) and the last expression statement's value is returned. Longer code, and code the parser refuses, runs once as written; nothing is retried on what an error says.

  • --secrets masks whole values. A value of 4 characters or more that appears whole in a tool's result or error, as written or under the encodings listed in the security notes (up to six layers), is shown as <secret:NAME>; masking a reply of 100 000 characters adds under 3 seconds. Not masked: a part of a value (a result cut by a size limit, the window inspect_dom was asked for, slice(), a value split across elements, requests or replies); a value transformed any other way (base64, hex, reversed, another case, hashed, an encoding not listed, more than six layers); what is not text (screenshots, PDFs, videos, saved files). It keeps known values from reaching the agent by accident; it is not a security boundary.

  • Header redaction in get_network_logs goes by name. A header's value is shown only when its exact name is on the allowlist; every other value is replaced unless include_sensitive_headers: true. A harmless header that is not on the list is hidden too. What the value of a listed header holds (a token a server puts in a Location URL) is not looked at: URLs and response bodies are returned as they are, and --secrets masks a known value in them.

  • WebSocket frames and closes in get_network_logs. For a socket of a tab the server already watches (its document, its frames, its dedicated workers): its frames, and one closed or failed line once it ends. On Firefox, what happens in a tab the page opened (a popup) before the debugger is attached to it is not recorded (the first frames of a socket opened at once, a handshake refused at once): Firefox cannot pause a new tab. A socket still open by then is listed closed when it ends.

  • Mocked routes answer requests. A route (mock_route) answers the requests its glob matches, before they reach the network; it does not change a response the server sent. Every request the browser holds for a route is answered: with the route's response, let through, or failed when the browser refuses the response (list_routes then shows the browser's error); removing a route lets through what it held. get_network_logs shows what the browser reported. Not promised: a request the page starts while a route is being added or removed may or may not be matched.

Reporting issues

Please report problems in the issues, with the version and a reproduction. Severity:

  • High: a security boundary fails (--local, the file path restrictions, the tool-group and cookie-import gates, a secret written to the logs), the server panics, exits or deadlocks, a tool does not answer within its documented timeout, or the server loses data it had recorded.

  • Medium: in ordinary use (a tool's main purpose, with arguments an agent would send, on a normal page), a sentence of this README or of a tool's description is broken, or a tool reports something that did not happen. An opt-in tool group is ordinary use too.

  • Low: anything else, including what needs a rare input value, a race, load (tens of concurrent requests), an input at a documented limit, or a secondary option on one browser.

A page request a tool leaves pending is a bug, but not a hang of the server while every tool still answers: rate it by how often an agent meets it. For the five convenience features, what is outside their stated scope is not a bug.

Limitations and TODO

  • TODO Default window size from the screen size: launched browsers use --window-size (default 1920x1080 on both); reading the screen size needs native APIs per OS, left out of the server.

  • TODO pause_on_load on Firefox: neither a preload debugger; statement nor an RDP interrupt pauses a reloading page (spike verdict).

  • TODO rust-mcp-sdk 2.0: the server stays on 1.1.0 (MCP protocol 2025-11-25). 2.0 moves to the stateless MCP protocol (2026-07-28), which today's MCP clients probably do not speak yet; upgrade once the clients do.

  • On Firefox, a reload with disable_cache: true bypasses the cache with network.setCacheBehavior (Firefox rejects ignoreCache on browsingContext.reload); a reload Firefox aborts with NS_BINDING_ABORTED is retried once after 50 ms.

  • get_performance_metrics and profile_page_performance are partial on Firefox: it has no Performance or Tracing domain, so they read what the Web Performance APIs give and say what is missing (JS heap, layout and style counts, long tasks, total blocking time).

  • lighthouse_report is partial on Firefox: WebDriver BiDi has no CPU or network throttling, touch emulation or trace, so the load runs at full speed, FCP and LCP come from the Web Performance APIs, TBT, CLS and Speed Index are null and performance has no score (the other three categories are scored). On both browsers it is Lighthouse-style, not Lighthouse: throttling is applied (Lighthouse simulates it by default), TBT runs to the end of the trace instead of Time to Interactive, and the other categories weigh the audit_page checks, fewer than Lighthouse's audits.

  • Firefox WebSocket frames and page errors need the Firefox debugger port (WebDriver BiDi has no WebSocket frame events); binary frames are reported as Firefox gives them, not base64 as on Chrome.

  • webmcp_list_tools, webmcp_invoke_tool, webmcp_get_invocation, webmcp_list_invocations and webmcp_cancel_invocation are Chrome only (a Chrome testing feature).

  • record_video is Chrome only (156 or later): WebDriver BiDi has no video recording.

  • send_cdp_command is Chrome only; send_bidi_command and send_rdp_request are Firefox only.

  • Cookie import (--allow-cookie-import) and launch presets (features) are Chrome only.

  • Firefox breakpoints are set by URL only.

  • --local checks the URLs the server navigates to and the known navigation methods of the raw tools. navigate (also history back or forward), open_tab, reload and lighthouse_report also check where the tab ended: on a network address that is not local (after a redirect, say) they fail naming its origin, and the tab goes back to about:blank (the error says if that failed), also when that page opened a dialog while loading or right after (the dialog is dismissed first) or paused in the debugger (the pause is resumed first; Chrome also ends the paused script). The browser follows a redirect before the server sees it, so that request was already sent. lighthouse_report without url refuses a current page that is not local before loading it. The raw tools and the enable_proxy_auth pre-warm page are checked only before they start; the reloads of profile_page_performance and pause_on_load are not checked. JavaScript running in the page can still navigate anywhere, and the page's own requests (images, scripts, fetch) are not restricted.

  • Firefox: after a lost connection a launched Firefox gets a new session on the next tool call; an attached Firefox keeps its orphan session, so restart that Firefox.

  • Firefox debugger: tabs are mapped to the debugger through Firefox's Remote Agent (verified on Firefox 157 to 159); a Firefox without it answers the debugger tools with an error instead of guessing a tab.

  • get_network_logs with include_details: true has no total size limit (each Firefox body is capped at 2 MB): use url_filter on busy pages.

  • The Docker image is amd64 only.

  • Frames of another origin: evaluate_js runs in the page only, and capture_screenshot cannot clip to an element inside such a frame (pass the iframe's ref instead); snapshot reads at most 20 of them, 5 deep; the coordinates in the replies of the input tools are the frame's. On Chrome, the console and network of at most 50 of them per tab are logged, and the debugger reaches their scripts (ids such as 2.17: frame 2's script 17), as it does on Firefox; pause_on_load pauses the page only.

Untested

  • Proxy authentication on Firefox against a real proxy.

  • macOS and Windows with real browsers (CI builds and unit-tests them; the E2E smoke ran on Linux only).

  • Firefox ESR.

  • The Docker image on arm64.

  • The Windows clippy cross-check (make clippy-windows) on a machine with mingw.

Security notes

  • --allow-cookie-import copies your real Chrome cookies into an isolated profile; the agent must ask you before using copy_cookies.

  • cookies and web_storage hide values (often session tokens) unless show_values: true; values never reach the logs.

  • Downloads are written only to the instance's downloads directory (see --downloads-dir): a suggested name keeps only its file name, an instance's folder only lowercase letters, digits, -, _ and ~ (any other byte of the label is written ~ and two hex digits, a/b as a~2fb and A as ~41, and an empty label or a device name Windows reserves gets a trailing ~, so two instances never share a folder), and an existing file is never replaced. open_instance refuses a label whose folder name would be longer than the 255 bytes file systems take (85 characters outside a-z0-9-_), and a downloads directory that cannot be created or written (a read-only folder) denies every download: the browser never saves to its own default folder instead, and the folder is left as it is.

  • upload_file hands the page a file's contents: it only reads files under the upload roots (the server's working directory and the system temp directory, or the --upload-root directories), resolved so .. and symlinks cannot leave them. The browser gets the resolved path, so a symlink repointed after the check cannot lead it out (the page sees the name of the file a symlink points to). Paths are never logged.

  • --secrets <file> keeps known values (test passwords, API keys) out of what the agent reads: every tool result and error (text, embedded text, structured content) shows them as <secret:NAME>, as they are and under up to six layers, nested in any order, of JSON and JavaScript string escapes (\", \\, \/, \', \n, \uXXXX in lower- or uppercase and as surrogate pairs, \u{...}, \xXX: JSON.stringify, Python's json.dumps, PHP, Go, Gson), HTML character references (&amp;, &lt;, &gt;, &quot;, &apos;, &nbsp;, decimal and hexadecimal: an inspect_dom, an innerHTML, a server's escaper) and percent-encoding (a form with + for a space, encodeURIComponent, encodeURI, escape(), upper- or lowercase hex): the server decodes the reply layer by layer and replaces each value where it was written, also when the value shares an escape with the text around it (a trailing \ before an attribute's closing quote) and when two secrets overlap. Only a whole value is masked: see Scope of the convenience features for what is not. And fill_input / fill_form type the value of a <secret:NAME> they are given, so the agent can log in without seeing the password. It is a convenience, not a security boundary: a part of a value (a result cut by a size limit, a window the caller chose, slice()), a value the page encodes otherwise (base64, a hash) or transforms (splits it, changes its case) is not masked, nor are images (screenshots, PDFs); and the server stops at start-up if the file has a malformed line, a value shorter than 4 characters or a name defined twice (the error names the line, never a value). Values never reach the logs.

  • save_pdf writes only .pdf files, under the same upload roots and resolved the same way; it overwrites an existing .pdf there. The same holds for the .mp4 of record_video and the save_path of profile_page_performance. A path that is a symlink is followed only to an existing file under the roots (a dangling one is refused). The file is written from a handle on its upload root, never by its whole path again: a directory swapped for a symlink after the check fails the write, and a symlink created at the file is replaced, not followed (a new file is moved into place).

  • The proxy password is never logged and is given only to proxy (407) challenges, never to a site's own authentication.

  • The Firefox debugger port needs devtools.chrome.enabled: any local process that reaches that port gets chrome (privileged) access to the browser. Use --no-firefox-debugger when you do not need the debugger.

  • Header values are shown only for the standard headers known to carry no credential, each by its exact name, never by how a name starts (the list is SHOWN in src/util/headers.rs: content negotiation, caching, the CORS Access-Control-* headers, the fetch metadata and client hints browsers send, security policies, Location, Origin, Referer, User-Agent, request ids such as X-Request-Id and traceparent, the WWW-Authenticate challenge...; _ counts as -). Every other header's value (Authorization, Cookie, Set-Cookie, an app's or a vendor's own header such as X-Api-Key, X-WP-Nonce or CB-ACCESS-SIGN, and Sec-WebSocket-Protocol, where apps put tokens) and request bodies are redacted in get_network_logs unless include_sensitive_headers: true. URLs and response bodies are returned as they are.

  • Logs carry tool names, ids, protocol method names and sizes, never payloads, cookies or URLs with queries, whatever RUST_LOG asks for: the libraries that log protocol payloads, proxy URLs or wire frames (the CDP client, the MCP transport, reqwest, the WebSocket and HTTP crates) are capped at info, also when RUST_LOG names one of their modules.

Development

make check        # fmt, clippy -D warnings, tests, docs, duplication, packaging, version
make e2e          # E2E smoke against real Chrome and Firefox, headless (E2E_VISIBLE=1 shows them; Linux, macOS)
make regressions  # the reproductions of the closed GitHub issues (tests/regressions)
make check-all    # all three
make compare      # the same tasks on this and other browser MCP servers (tests/compare)

make check is hermetic: it never starts a browser or touches the network. make e2e runs tests/run_all_e2e.sh: the launched-mode smoke for both browsers, then the attach mode against browsers started by tests/chrome.sh and tests/firefox.sh (Chrome 156 or later: it records a video and evaluates in an enclosing scope), then the differential checks of tests/differential, where the browser itself is the oracle (fuzz_tla.py: evaluate_js with top-level await against the page's own eval of thousands of generated statements; --sample 0 runs all of them), and ws_matrix.py: a WebSocket of the document, a same- or cross-origin iframe, a nested iframe, a worker and a popup, ended by the page, the server, a dropped connection, a navigation, a reload, a removal or terminate(), or refused, unanswered or dropped at the handshake, must get exactly one close line in get_network_logs, and headers.py: credential request, response and cookie headers are hidden and standard ones shown, by default and in one request's details, and secrets.py: a secret the page writes through its encoders into 34 places a tool reads (values, errors, the console, the DOM, the snapshot, requests, storage, the tab's URL) shows in no reply. make regressions runs the reproduction scripts of the closed GitHub issues, saved in tests/regressions by its fetch.py: an issue fails when its script shows its bug again (the issues closed with a documented deviation are skipped, saying why). make compare runs the scenarios of tests/compare (from common tasks to rare ones, each with a check) on browser-control and on Playwright MCP, chrome-devtools-mcp and a Puppeteer MCP, and compares the outcome, calls and tokens with a saved baseline. See AGENTS.md for the conventions.

Releasing

For the maintainer: a version is X.Y.Z, or X.Y.Z-rc.N for a release candidate (with the dot: the MSI installer turns N into its fourth version field, and wix/main.wxs lets a candidate replace the one before it). Bump it in Cargo.toml, package.json and Cargo.lock (cargo check), and in this README's status line and cargo install --version lines; close the [Unreleased] section of CHANGELOG.md, run make check-all, tag vX.Y.Z (or vX.Y.Z-rc.N) and push the tag (the release workflow builds the installers and publishes npm and Homebrew; it needs the NPM_TOKEN and HOMEBREW_TAP_TOKEN secrets), then cargo publish by hand.

License

MIT, see LICENSE.

Available Tools

31 tools
capture_screenshotA
Read-only

Screenshot of the tab's viewport, of the whole page with full_page, or of one element with selector (at most 16384 CSS pixels per side; a larger capture gets a note). To find elements to act on, prefer 'snapshot'.

Inputs: format, tab_id, quality, selector, +2 more.

click_elementA

Clicks an element with real mouse input after scrolling it into view; waits up to 2 s for a CSS selector's element to appear or be enabled, and fails without clicking when it is hidden, covered (naming the overlay) or disabled. A dialog or breakpoint the click triggers is noted in the reply ({dialog} or {paused, location}), not an error: continue with handle_dialog or resume (evaluate_on_call_frame, with --tool-groups debug, reads the paused frame).

Inputs: selector (required), button, tab_id, modifiers, +2 more.

close_instanceA

Stops an instance: other instances are removed; 'default' is stopped and relaunched on its next use.

Inputs: instance_id (required).

close_tabA

Closes a tab (default: the active one); the most recently active open tab (else the newest) becomes active and is brought to the front. Returns {closed_tab_id, active_tab_id}.

Inputs: tab_id, instance_id.

dragA

Drags an element onto another with the mouse, for sortable lists, boards, sliders and HTML5 drag and drop: presses on 'from' (scrolled into view; waits up to 2 s for it to appear or be enabled; fails when hidden, covered or disabled), moves in steps to the centre of 'to' (which must be in the viewport) and releases. Firefox simulates HTML5 drag and drop with script events.

Inputs: to (required), from (required), tab_id, instance_id.

evaluate_jsA

Evaluates JavaScript in the page and returns its value (promises awaited; top-level await works in code up to 64 KB that parses, the last statement giving the value; other code runs as written): {value, type, subtype?, description?, preview?}. value is the JSON form; a Map, Set, typed array, Error, cycle or throwing getter gets a bounded preview (preview: true; a Map as [key, value] pairs, a Set or typed array as items, an Error as {name, message, stack}, '[Circular]', '[Thrown: message]') that description names (Map(2), TypeError: bad); functions, nodes and symbols give null, described (a function's source). Cut over 100000 characters (truncated: true). An exception fails with its message, and its 1-based line and column when they are in the expression. user_gesture: true lets the expression call APIs that need a user action (requestFullscreen, clipboard writes, window.open past the popup blocker); off by default, as the page then gets that power. In a paused frame use evaluate_on_call_frame (--tool-groups debug). Chrome stops a script after 8 s; Firefox cannot (close a frozen tab with close_tab).

Inputs: expression (required), tab_id, instance_id, user_gesture.

fill_formA

Fills several fields in one call, in order: text fields and s as fill_input does; a checkbox or radio takes 'true' or 'false' and is clicked only when its state differs. Returns each field's outcome (filled, selected, checked, unchecked, unchanged), never the values; stops at the first failing field, naming it and what was done.

Inputs: fields (required), tab_id, instance_id.

fill_inputA

Types into a text field, textarea or contenteditable, replacing its content (or after it with append), key by key so the page's handlers run (~1 ms per character); picks the option(s) named; sets a date, time, range or colour input (YYYY-MM-DD, HH:MM, a number, #rrggbb). Fails without typing on disabled, read-only, non-text or unfocusable elements and when the field rejects the text; notes a reformatted value. For several fields at once use fill_form.

Inputs: text (required), selector (required), append, tab_id, +1 more.

find_in_snapshotA
Read-only

Searches the whole 'snapshot' outline (never cut) and returns only the matching lines under their ancestors, with their refs (at most 20 matches). Cheaper than 'snapshot' on a large page.

Inputs: text, regex, tab_id, instance_id.

get_console_logsA

Lists the tab's console messages and uncaught exceptions, oldest first, one line each: [level] text @ url:line (lines from 1; objects previewed, repeats folded, stacks indented); on Chrome an uncaught error's cause chain follows it (Caused by: lines); include_details gives {messages, total, truncated, notes?} as JSON. Keeps the last 1000 (10000 characters each); cleared when the tab moves to another site. For problems the browser diagnosed (blocked cookies, CORS, CSP) use get_issues.

Inputs: clear, limit, tab_id, instance_id, +2 more.

get_css_stylesA
Read-only

Explains why an element looks as it does: the CSS rules matching it, highest priority first (style attribute, then rules), each with selector, stylesheet URL (the page's for an inline ), 0-based line and column, enclosing at-rules (@media, @container, @layer, @supports) and declarations marked important, invalid or overridden; its pseudo-elements; and the computed values of the declared properties. Options add the ancestors' rules (nearest first) and the browser's, or narrow to some properties (declarations included). Firefox reads them with its inspector (needs its debugger port).

Inputs: selector (required), tab_id, max_rules, properties, +3 more.

get_issuesA

Lists the problems the browser diagnosed in the tab that the console hides or words vaguely: blocked or warned cookies and why, CORS and Content-Security-Policy blocks, mixed content, deprecated features, and on Chrome every code of its DevTools Issues panel (form fields without id, name or label, LazyLoadImageIssue...). One line each, oldest first: [code] title: summary @ url [xN] (a title for the common Chrome codes; N distinct reports, one per element or request), then on Chrome its elements (selector [ref=eN], refs as snapshot's, at most 10). For console messages use get_console_logs. Firefox has no Issues panel: its security and deprecation console messages are read as issues (cookies, CSP, mixed content, CORS, DeprecationIssue; needs its debugger port).

Inputs: code, clear, tab_id, instance_id, +1 more.

get_network_logsA

Lists the tab's HTTP requests (id, method, URL, status, type; the last 3 navigations, oldest first) and WebSocket frames and closes, with filters. request_id or include_details gives headers and bodies (cut at 64000 characters; a body over 2 MB is omitted, with its size). A redirect chain is one request, found by any hop's URL; its details list each hop's status and Location. Request bodies and the values of headers other than standard ones known to hold no credential (an app's own X-... headers included) are redacted unless include_sensitive_headers.

Inputs: clear, tab_id, request_id, url_filter, +7 more.

handle_dialogA

Accepts or dismisses the JavaScript dialog (alert, confirm, prompt, beforeunload) open on the tab. While one is open, tools that run page code fail naming it. Returns {accepted, dialog}; fails when none is open.

Inputs: accept (required), tab_id, instance_id, prompt_text.

hoverA

Moves the mouse over an element (scrolled into view; fails when hidden or covered) so hover menus, tooltips and :hover styles appear.

Inputs: selector (required), tab_id, instance_id.

inspect_domA
Read-only

Returns the page's HTML (open shadow roots as , same-origin iframes appended after ; at most 100000 characters), or with 'query' the first match and its context. To find elements to act on, prefer 'snapshot'.

Inputs: after, query, before, tab_id, +1 more.

list_downloadsA
Read-only

Lists the files the instance's pages downloaded, oldest first (id, url, file_name, path once complete, state: in_progress, completed or canceled, sizes, tab_id), and their directory (a folder of --downloads-dir named after the instance id, else the instance's temporary profile, deleted with it). An action that starts a download also says where the file went.

Inputs: instance_id.

list_instancesB
Read-only

Lists the instances: id, browser, capabilities, label, host, port (0 until a Chrome the server launches has picked one), profile_dir, features, is_default.

Inputs: no named parameters.

list_tabsA
Read-only

Lists the instance's tabs: {active_tab_id, tabs: [{tab_id, label, target_id, url}]}.

Inputs: instance_id.

open_instanceA

Starts a new browser instance, Chrome or Firefox, with its own profile; its 'label' becomes the instance_id other tools take. Fails in --user-profile mode.

Inputs: label, proxy, browser, features, +1 more.

open_tabA

Opens a tab (launching the instance if needed; a fresh instance's untouched blank start tab is used, once, instead of opening a second one), makes it the active tab in front, and waits for 'url' to load. Returns {tab_id, target_id, url, label}; a network error fails naming the tab, which stays open.

Inputs: url, label, instance_id.

press_keyA

Presses one key, with modifiers (Control+a, Shift+Tab), as a user would, in the element given (focused first) or the focused one; the browser's default action runs (Enter submits, Tab moves the focus). With Control, Alt or Meta held nothing is typed. To type text use fill_input. A dialog or breakpoint it causes is noted, as for click_element.

Inputs: key (required), tab_id, selector, modifiers, +1 more.

reloadA

Reloads the tab and waits for load (at most 30 s; a page that pauses at a breakpoint or opens a dialog while loading fails at once saying so). Returns the same shape as 'navigate'.

Inputs: tab_id, instance_id.

restart_browserA

Restarts an instance's browser (closing its tabs), optionally with another proxy or presets. A browser the server attached to (not launched) is not restarted: the call fails saying so.

Inputs: features, instance_id, proxy_server.

resumeA

Resumes a page paused in the debugger (a breakpoint, a step, an exception or its own debugger statement). Returns {paused, location: {url, line_number, column_number} | null} (0-based): paused only if it stopped again within 250 ms (another breakpoint).

Inputs: tab_id, instance_id.

scrollA

Scrolls the window by pixels or viewport heights, or brings an element into view; wheel: true sends a real mouse wheel event instead, for a canvas or map. Returns the window positions {before, after, element_in_view?} and says when nothing moved (on a page that scrolls an inner element, pass a selector inside it).

Inputs: x, y, pages, wheel, +3 more.

snapshotA
Read-only

Outlines the page to act on it: one line per element with a role (button, link, textbox, heading...), name, states, value and a ref ([ref=e12]), indented under its parent; an invalid field shows [invalid] [error='why'], a its first 25 options (pick one with fill_input); through open shadow roots and iframes (another origin's frame is [frame=f2], refs f2e5; selector 'f2' outlines it alone); hidden elements left out, passwords never shown; at most 50000 characters (find_in_snapshot searches it whole). Refs work as the selector of the input tools until the page navigates. Same on Chrome and Firefox.

Inputs: depth, tab_id, selector, instance_id.

stop_browserA

Stops an instance's browser and closes its tabs; other instances keep running. A browser the server attached to (not launched) is only disconnected.

Inputs: instance_id.

switch_tabA

Makes a tab the target of the tools that omit tab_id, and brings it to the foreground unless 'activate' is false.

Inputs: tab_id (required), activate, instance_id.

wait_forA
Read-only

Waits until every condition given holds: visible text appears or disappears (open shadow roots and same-origin iframes included), an element reaches a state, or the URL contains a text; checks every 100 ms. Returns the time waited; on timeout it fails naming what is missing. A dialog or debugger pause ends it at once.

Inputs: url, text, state, tab_id, +4 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 31 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes (click vs fill vs press_key vs hover vs drag; snapshot vs inspect_dom; console vs issues vs network logs). The main blur is among lifecycle tools: stop_browser, restart_browser, and close_instance overlap in meaning, and fill_input vs fill_form require reading descriptions to separate. These are minor compared with the strongly partitioned rest of the surface.

    Naming Consistency4/5

    Dominant snake_case verb_noun pattern (capture_screenshot, open_tab, get_network_logs, list_downloads) with predictable prefixes for read/list/create lifecycle. Deviations exist: bare verbs (hover, drag, scroll, reload, resume, navigate) and a lone noun (snapshot), but the grouping remains readable and predictable.

    Tool Count3/5

    31 tools is heavy for a browser server, though the breadth (interaction, DOM, network, console, CSS, tabs, instances, downloads, debugging) justifies much of it. Some consolidation is possible - stop_browser/restart_browser vs close_instance, and find_in_snapshot as a helper to snapshot - so the count is borderline rather than well-scoped.

    Completeness4/5

    Coverage is unusually thorough: navigation, snapshot/DOM inspection, full input simulation, network and console logs, browser-diagnosed issues, CSS inspection, dialogs, debugger pauses, and instance/tab/download management. Gaps remain around file uploads, cookie/storage/state management, and network interception or viewport/device emulation, which agents will occasionally need.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers