browser-control
Allows an AI agent to control and debug Firefox through WebDriver BiDi and Firefox RDP, with the same browser-control tools for navigation, DOM and input interaction, screenshots, console and network capture, breakpoints, call frames, stepping, and script search.
Allows an AI agent to control and debug Google Chrome through CDP, including navigation, DOM and input interaction, screenshots, console and network capture, breakpoints, paused-frame evaluation, call frames, stepping, and script search.
browser-control-mcp
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; | ✗ | ✗ |
Firefox | ✓ next to Chrome, same tools | ✓ one browser per server | ✗ |
Several browsers and instances at once | ✓ | ✗ | ✗ |
Selectors | CSS, snapshot refs, | CSS, snapshot refs | snapshot refs only |
Frames of another origin (payment forms, embedded editors) | ✓ in the snapshot, refs | ✓ refs | ✗ |
Snapshot of a long page | bounded at 50 000 characters, | 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 |
✓ file or inline | ✓ file | ✗ | |
Cookies and web storage | ✓ values hidden unless asked | ✓ values shown | ✗ |
Secrets masked in output ( | ✓ a whole value, as written and JSON-, HTML- or URL-encoded (up to six layers) | ✓ the literal text only: a value with | ✗ |
| ✓ statements as in a console ( | ✗ takes a function ( | ✗ takes a function; |
Credential headers in a request's details ( | hidden by default: only the standard headers on an allowlist of exact names show their value | shown | shown; |
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 | trace file | trace + insights; CPU and network throttling |
Page audit (accessibility, SEO, best practices) | ✓ | ✗ | 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, | 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 | 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 | 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 | 4 ms | 178 ms; 455 ms with | 280 ms; 542 ms with |
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 | 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 ...@latestcommand the other READMEs give also asks the npm registry for the latest version each time it starts (checked withnpx --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
nodebinary alone is 150 MB in v26.13.0 on Linux), npm ornode_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 orcargo install.Work on each reply is cheap.
--secretsmasks a 100 000-character reply with 100 overlapping secrets in about 10 ms, and top-levelawaitis found by a native JavaScript parser, in the server's own process.A bug fails one call, not the session.
unsafecode is denied, andunwrap,expectandpanic!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 |
|
| the JavaScript debugger: 10 tools only a debugging session needs ( |
|
| reads and changes session tokens |
|
| reads and writes files of the machine |
|
| anything the protocol allows |
|
| niche |
|
| niche |
|
| 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 |
| ✓ | partial |
|
| ✓ | ✓ | |
| ✓ | ✓ | each instance reports its |
| ✓ | ✓ | was |
| ✓ | ✓ | was |
| ✓ | ✓ | 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 |
| ✓ | ✓ |
|
| ✓ | ✓ | tabs in the order they were opened ( |
| ✓ | ✓ | the files the instance's pages downloaded, oldest first ( |
| ✓ | ✓ | |
| ✓ | ✓ |
|
| ✓ | ✓ | a pause, a dialog or HTTP authentication while loading fails at once, as with |
| ✓ | ✓ | reports the window positions before and after; |
| ✓ | partial |
|
| ✓ | ✓ | waits (checking every 100 ms, at most 30 s) until a visible text appears or is gone, a selector is |
| ✓ | ✓ | includes open shadow roots and same-origin iframes (cross-origin ones are noted); at most 100 000 characters without |
| ✓ | ✓ | why an element looks as it does: the rules that match it, highest priority first (the |
| ✓ | ✓ | outline of the page: role, name, states, value and a ref ( |
| ✓ | ✓ |
|
| ✓ | ✗ |
|
| ✓ | ✓ |
|
| ✓ | ✓ |
|
| ✓ | ✓ | scrolls the element into view; |
| ✓ | ✓ | picks |
| ✓ | ✓ | one key (a character, Enter, Tab, Escape, arrows, F1–F12...) with Control / Shift / Alt / Meta held (in |
| ✓ | ✓ | moves the mouse over the element (scrolled into view; fails when hidden or covered) |
| ✓ | ✓ | presses on |
| ✓ | ✓ | several fields in one call: text and |
| ✓ | ✓ |
|
| ✓ | ✓ | accepts or dismisses the open |
| ✓ | ✓ |
|
| ✓ | ✓ |
|
| ✓ | ✓ |
|
| ✓ | ✓ | one line per message, oldest first: |
| ✓ | partial | the problems the browser diagnosed that the console hides or words vaguely, one line each, oldest first: |
| ✓ | ✓ | 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 ( |
| ✓ | ✓ |
|
| ✓ | ✓ |
|
| ✓ | ✓ |
|
| ✓ | ✓ |
|
| ✓ | ✓ |
|
| ✓ | partial |
|
| ✓ | partial |
|
| ✓ | ✓ |
|
| ✓ | partial |
|
| ✓ | partial |
|
| ✓ | ✓ |
|
| ✓ | ✓ | always listed (a page can pause itself); on a page that is not paused: |
| ✓ | ✓ |
|
| ✓ | ✓ |
|
| ✓ | ✓ |
|
| ✓ | ✓ |
|
| ✓ | ✓ |
|
| ✓ | ✓ |
|
| ✓ | ✓ |
|
| ✓ | ✗ |
|
| ✓ | partial | needs |
| ✓ | ✗ |
|
| ✗ | ✓ |
|
| ✗ | ✓ |
|
| ✓ | ✗ | needs |
| ✓ | ✗ | needs |
| ✓ | ✗ | needs |
| ✓ | ✗ | needs |
| ✓ | ✗ | needs |
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 unscopedbrowser-control-mcpon 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-mcpThe 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 install3. 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 | sh4. 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 compile5. 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 install2. 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 | shThe 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-mcp4. 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 compile5. 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 install2. 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 compile5. 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 insideFrom 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-mcpTo 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
defaultinstance always exists and uses the--browserflag.open_instancewith alabelstarts another one (its id is the label), withbrowserto 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 takesinstance_idandtab_id; without them it targets the default instance and its active tab. The active tab is the one the browser shows:open_tabmakes its new tab active,close_tabbrings the next one to the front, and after a page opens or closes a tab (atarget=_blanklink, 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, andopen_tabdoes. On Chrome a tab whose page crashed is refused at once, namingreload. Background tabs are hidden to their pages (norequestAnimationFrame, throttled timers). An argument a tool does not have fails the call before anything runs (atabIdtypo answers "did you meantab_id?"), so a typo never falls back to the active tab.Same replies on both browsers.
navigateandreloadanswer once the page firedload(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": {...}}, wherebrowserholds the protocol's ids (CDPframeId/loaderId, BiDinavigation), 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 withNavigation failed: the URL is a download...; the file is still saved (seelist_downloads).open_tabanswers{tab_id, target_id, url, label}with the final URL. A network error (unknown host, refused connection...) fails withNavigation failed: <browser's code> (<url>), e.g.net::ERR_NAME_NOT_RESOLVEDon Chrome andNS_ERROR_UNKNOWN_HOSTon Firefox; fromopen_tabthe error names the tab, which stays open.evaluate_jsanswers{"value", "type", "subtype"?, "description"?}:typeis JavaScript'stypeof,subtyperefines objects (array,null,node,date,map...),valueis the JSON form and isnullwhen there is none (functions, DOM nodes, symbols,NaN, bigints, maps...),descriptionthen says what it was (Chrome describes functions by their source, Firefox only asfunction). An object or array'svalueis whatJSON.stringifygives, on both browsers (toJSONcounts: aURLis itshref; nested functions drop out), and an object that is not a plain one has its class indescription(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). Avalueover 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.
snapshotoutlines 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_snapshotreturns only the lines that match, under their ancestors. Theselectorofclick_element,fill_input,scrollandwait_fortakes such a ref, a CSS selector, orhost >>> innerto 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 asf2e5, which every selector argument takes, as doesf2 >>> css; the input tools then check and act in that frame (one call acts in one document:fill_formanddragrefuse 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.kzanddocs.knot.kzare one site,a.github.ioandb.github.iotwo) and kept across reloads and same-page navigations.get_console_logsanswers{"messages": [...], "total", "truncated", "notes"?}: at mostlimit(default 200) of the most recent matching messages, oldest first;clearremoves only the returned ones; a note says when a site change cleared messages.get_custom_eventsanswers{"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_browserand every server shutdown path end it, so the next run can attach again.
CLI flags
Flag | Default | Chrome | Firefox |
|
| browser of the default instance | browser of the default instance |
| off | navigation limited to local addresses | same |
| off | headless Chrome (also the default of | headless Firefox (same) |
|
| window of launched Chrome ( | window of launched Firefox ( |
|
| debugging host | debugging host |
| none (launch) | without it the default instance launches a Chrome of its own on a free port ( | ignored (use |
|
| instance cap, the default instance included (its slot is held before its first use) | shared with Chrome |
| off | shows the automation infobar | ignored; |
| off | your default profile (no | only with |
| off | exposes | capability error |
| none | dotenv file ( | same |
| none | lists the opt-in tool groups, comma separated: | same |
| working + temp dir | directory | same |
| inside the instance's profile | each instance saves downloads in a folder of | same; snap Firefox can only write to non-hidden folders of |
| off | WebMCP switches and | capability error |
| none | proxy for every instance ( |
|
| none | answers proxy (407) challenges | same (untested) |
| none | never logged | same |
| discovered | — | Firefox binary to launch |
| none (launch) | — | attach to a running Firefox's BiDi port |
| none | — | debugger port of the attached Firefox (needs |
| 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:
navigateto the page (oropen_tab).search_scriptswith a needle to find the script URL and line.set_breakpointwithurlandline_number(0-based).Trigger the code (
click_element,evaluate_jswith asetTimeout, a reload...). The page pauses. Aclick_elementwhose handler hits the breakpoint answers at once, as a success: the click happened, and the reply addsThe 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.call_stacklists the paused frames and why the page paused;evaluate_on_call_framereads locals of the paused frame (or of a caller, withframe_index);step_overmoves one statement,step_intoenters a call,step_outreturns to the caller;resumecontinues. 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 afterresume.evaluate_jsstill 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.remove_breakpointwith the idset_breakpointreturned.
Both browsers answer the same replies, with 0-based lines everywhere:
Tool | Reply |
|
|
|
|
|
|
| the |
|
|
|
|
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 |
|
npm |
|
tool |
|
tool |
|
replies printed as Rust | prefix + pretty JSON of the reply |
|
|
| 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 |
| Chrome: raw |
|
| Chrome: success ( | error |
| Chrome: |
|
| Chrome: CDP id ( |
|
| Chrome: CDP id, reply |
|
| Chrome: text only; Firefox |
|
| Chrome: raw | the |
|
|
|
| a JSON array; |
|
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_jsruns 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-levelawaitworks for code of up to 64 KB that parses as JavaScript: it runs inside an async function (so itsvarand 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.--secretsmasks 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 windowinspect_domwas 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_logsgoes by name. A header's value is shown only when its exact name is on the allowlist; every other value is replaced unlessinclude_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 aLocationURL) is not looked at: URLs and response bodies are returned as they are, and--secretsmasks 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 oneclosedorfailedline 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_routesthen shows the browser's error); removing a route lets through what it held.get_network_logsshows 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_loadon Firefox: neither a preloaddebugger;statement nor an RDP interrupt pauses a reloading page (spike verdict).TODO
rust-mcp-sdk2.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: truebypasses the cache withnetwork.setCacheBehavior(Firefox rejectsignoreCacheonbrowsingContext.reload); a reload Firefox aborts withNS_BINDING_ABORTEDis retried once after 50 ms.get_performance_metricsandprofile_page_performanceare 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_reportis 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 arenulland 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 theaudit_pagechecks, 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_invocationsandwebmcp_cancel_invocationare Chrome only (a Chrome testing feature).record_videois Chrome only (156 or later): WebDriver BiDi has no video recording.send_cdp_commandis Chrome only;send_bidi_commandandsend_rdp_requestare Firefox only.Cookie import (
--allow-cookie-import) and launch presets (features) are Chrome only.Firefox breakpoints are set by URL only.
--localchecks the URLs the server navigates to and the known navigation methods of the raw tools.navigate(alsohistoryback or forward),open_tab,reloadandlighthouse_reportalso 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 toabout: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_reportwithouturlrefuses a current page that is not local before loading it. The raw tools and theenable_proxy_authpre-warm page are checked only before they start; the reloads ofprofile_page_performanceandpause_on_loadare 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_logswithinclude_details: truehas no total size limit (each Firefox body is capped at 2 MB): useurl_filteron busy pages.The Docker image is amd64 only.
Frames of another origin:
evaluate_jsruns in the page only, andcapture_screenshotcannot clip to an element inside such a frame (pass the iframe's ref instead);snapshotreads 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 as2.17: frame 2's script 17), as it does on Firefox;pause_on_loadpauses 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-importcopies your real Chrome cookies into an isolated profile; the agent must ask you before usingcopy_cookies.cookiesandweb_storagehide values (often session tokens) unlessshow_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/basa~2fbandAas~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_instancerefuses a label whose folder name would be longer than the 255 bytes file systems take (85 characters outsidea-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_filehands 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-rootdirectories), 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,\uXXXXin lower- or uppercase and as surrogate pairs,\u{...},\xXX:JSON.stringify, Python'sjson.dumps, PHP, Go, Gson), HTML character references (&,<,>,",', , decimal and hexadecimal: aninspect_dom, aninnerHTML, 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. Andfill_input/fill_formtype 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_pdfwrites only.pdffiles, under the same upload roots and resolved the same way; it overwrites an existing.pdfthere. The same holds for the.mp4ofrecord_videoand thesave_pathofprofile_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-debuggerwhen 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
SHOWNin src/util/headers.rs: content negotiation, caching, the CORSAccess-Control-*headers, the fetch metadata and client hints browsers send, security policies,Location,Origin,Referer,User-Agent, request ids such asX-Request-Idandtraceparent, theWWW-Authenticatechallenge...;_counts as-). Every other header's value (Authorization,Cookie,Set-Cookie, an app's or a vendor's own header such asX-Api-Key,X-WP-NonceorCB-ACCESS-SIGN, andSec-WebSocket-Protocol, where apps put tokens) and request bodies are redacted inget_network_logsunlessinclude_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_LOGasks 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 atinfo, also whenRUST_LOGnames 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 toolscapture_screenshotARead-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_snapshotARead-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_stylesARead-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_domARead-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_downloadsARead-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_instancesBRead-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_tabsARead-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.
snapshotARead-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_forARead-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
Scored across 31 tools
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.
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.
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.
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
Related MCP Connectors
MCP server for understanding Javascript internals from ECMAScript specification.
MCP server to assist with JxBrowser development.
Live browser debugging for AI assistants — DOM, console, network via MCP.
A remote MCP server to convert HTML documents (URL or raw source) to PDF or screenshots
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP Server for Chrome DevTools, following the Chrome DevTools Protocol. Integrates with Claude Desktop and Claude Code.316MIT
- AlicenseNot gradedqualityDmaintenanceA Chrome DevTools Protocol-based MCP server that enables AI coding assistants to control browsers for JavaScript debugging, reverse engineering, web scraping, and API debugging.1Apache 2.0
- FlicenseNot gradedqualityDmaintenanceMCP server that connects to your browser to capture screenshots, inspect console logs, network requests, and more via Chrome DevTools Protocol.2-
- AlicenseNot gradedqualityDmaintenanceA lightweight MCP server that enables AI assistants to control Chrome DevTools via CDP for debugging tasks like navigation, screenshots, and JavaScript execution.MIT