Browser Rs Mcp

browser-rs

One real browser. Many agents. A ~5.5 MB Rust server.

[](https://github.com/maestrojeong/browser-rs-mcp/actions/workflows/ci.yml) [](https://github.com/maestrojeong/browser-rs-mcp/releases) [](LICENSE)

browser-rs is a lightweight, stealth-oriented browser MCP server. It lets multiple AI agents share one logged-in Chrome — each agent controls only its own tabs — for parallel scraping, web automation, and QA without every agent spinning up its own browser. 67 Playwright-style tools, one Rust binary, no Node.js runtime.

flowchart LR
    A["Agent Aowner=research"] --> M["browser-rs MCPone Rust process"]
    B["Agent Bowner=operations"] --> M
    C["Agent Cowner=qa"] --> M
    M --> H["one shared Chromepersistent profile"]
    H --> T1["research tabs"]
    H --> T2["operations tabs"]
    H --> T3["qa tabs"]

Why browser-rs?

| | browser-rs | Playwright/Puppeteer-based MCP (Node) | |---|:--|:--| | Server runtime | Single Rust binary | Node.js + npm dependency tree | | Release artifact | ~5.5 MB | Runtime and packages installed separately | | Server memory¹ | ~6 MB RSS | ~180 MB RSS | | Multi-agent control | One Chrome, owner-isolated tab groups | Separate coordination required | | Browser control | Raw CDP over one multiplexed WebSocket | Playwright |

The default mode uses a locally installed, headful Chrome with a persistent profile and does not inject page patches, minimizing common automation signals. It does not guarantee bot-detection bypass — no automation stack can — but ships reproducible detector runners under [bench/](./bench) so changes can be tested against current browsers and detectors. See [DESIGN.md](DESIGN.md) for how the stealth defaults work.

¹ Historical maintainer measurements excluding Chrome, taken from idle local servers. Exact memory varies by OS, build, runtime, and workload; treat these figures as an order-of-magnitude comparison, not a benchmark guarantee. The release binary size can be checked with du -h target/release/browser-rs.

Quick start

1. Install — on macOS arm64 and Linux x64 the installer downloads a prebuilt binary. A locally installed Google Chrome or Chromium is also required.

curl -fsSL https://raw.githubusercontent.com/maestrojeong/browser-rs-mcp/main/install.sh | sh
browser-rs --help

To pin this release instead of following latest:

curl -fsSL https://raw.githubusercontent.com/maestrojeong/browser-rs-mcp/main/install.sh | AB_VERSION=v0.1.22 sh

2. Run — use stdio for a client that launches the server:

browser-rs

3. Verify — point an MCP client at it and drive the browser:

browser_navigate  → https://example.com   # a headful Chrome window opens
browser_snapshot                          # returns the accessibility tree

The common workflow is: browser_snapshot, act, then inspect the returned accessibility diff. Most interaction tools accept a snapshot ref or a CSS selector.

Other install options — direct downloads, SHA-256 files, source builds, and updating a running binary — are in [INSTALL.md](INSTALL.md). To build from source:

cargo install --git https://github.com/maestrojeong/browser-rs-mcp ab-mcp

Set AB_CHROME if Chrome is not in a standard location.

What's new (v0.1.14 - v0.1.22)

v0.1.22 — exact pointer capabilities. Snapshot refs are unique capabilities bound to the page target and main-document loader, so navigation and later snapshots make old refs fail instead of silently retargeting them. The new browser_pointer tool adds right-click, double-click, horizontal/vertical scroll, and drag through either trusted CDP input or an explicit untrusted dom_event route. Trusted input retains humanized motion; DOM scrolling only succeeds when the selected scroll container actually moves.

v0.1.21 — opt-in background typing. browser_type waits for completion and returns its settle diff by default, preserving the existing action contract. Pass wait: false only when a later browser_cancel_typing call is needed.

v0.1.20 — cancellable typing. browser_type can run keyboard dispatch in the background so a later browser_cancel_typing call can stop it mid-flight. Long text (≥ 30 chars) uses a single CDP Input.insertText instead of char‑by‑char key events for speed. Call browser_cancel_typing({page}) to stop a running typing task mid-flight; already-typed characters remain.

v0.1.19 — out-of-process iframe support. Cross-origin iframe actions now route CDP commands through the iframe target's own flatten-mode session when Chrome Site Isolation places it in a separate renderer process (OOPIF). The session is carried together with the execution context through nested frame chains and reused across calls. This fixes structures such as a same-origin wrapper containing a cross-origin Kakao postcode iframe. The public iframe tool interfaces remain unchanged.

v0.1.18 — nested cross-origin iframe resolution. The iframe tools now resolve the selected iframe element directly to its CDP frame ID before falling back to URL/name matching, keep paths relative to the current frame context across repeated origin boundaries, and handle frames without src or name attributes. OOPIF target-session routing is completed in v0.1.19.

v0.1.17 — cross-origin iframe support. browser_iframe_click and browser_iframe_fill now work on cross-origin iframes, not just same-origin ones — same-origin frames still resolve with a single JS round trip, but a cross-origin boundary automatically falls back to CDP (Page.getFrameTree + Page.createIsolatedWorld), which isn't subject to the Same-Origin Policy. Both tools also support nested iframes via a Playwright-style " >> " chain in frame_selector (e.g. "iframe.wrapper >> iframe.popup"). A new browser_iframe_read tool reads outerHTML/innerText from inside an iframe with the same resolution logic — use it where browser_get_visible_html/_text/browser_snapshot can't see past a cross-origin boundary. browser_snapshot's accessibility tree also now always surfaces iframe nodes (even nameless ones) with a hint to use these tools, instead of silently pruning them. Frame resolution that would otherwise be ambiguous (e.g. two sibling iframes sharing a name or overlapping src) is rejected with an error rather than silently guessing and risking action in the wrong origin — see the frame_selector docs on browser_iframe_click/_fill/_read for the current known limitations (no CSS-aware >> escaping, no redirect tracking).

v0.1.14 — managed hosting security. browser-rs can now run behind a trusted host (like an agent platform) that spins up one server for many tenants. New in this mode: per-owner HMAC capability tokens, a fail-closed AB_ALLOWED_TOOLS allowlist, an optional secret broker that keeps the credential database and lookup logic out of browser-rs, and graceful shutdown that cleans up Chrome. See [Managed mode](#managed-mode-secure-multi-tenant-hosting) below.

v0.1.15 — safer output limits. Output truncation (snapshots, HTML, visible text, API responses) now respects UTF-8 character boundaries instead of cutting mid-character, and managed hosts can raise the internal limit so the secret broker redacts before truncation, not after.

v0.1.16 — output-limit hardening. A caller-supplied maxLength/maxBytes (e.g. usize::MAX) is now clamped to an absolute ceiling (AB_MAX_OUTPUT_LIMIT, default 5 MB — well above the 100k/200k tool defaults) so one managed tenant can no longer force an oversized response and degrade the shared process for everyone else.

Standalone stdio and unauthenticated loopback HTTP — the default for most users — are unaffected and keep their existing behavior.

Connect an MCP client

Example stdio configuration:

{
  "mcpServers": {
    "browser-rs": {
      "command": "browser-rs"
    }
  }
}

Use HTTP when several agents should share one browser process and profile:

browser-rs --port 9321
# streamable HTTP: http://127.0.0.1:9321/mcp
# legacy SSE:      http://127.0.0.1:9321/sse

Configure the client with http://127.0.0.1:9321/mcp for streamable HTTP, or /sse for clients that still use legacy SSE. Keep HTTP on loopback unless it is behind a trusted, authenticated proxy; non-loopback binds and the X-Browser-Capability header are covered in [INSTALL.md](INSTALL.md).

Multi-agent tabs

Each HTTP request identifies its topic, worker, or job with a stable owner (via an ?owner= query param or the X-Browser-Owner header). New tabs are assigned to the request owner, and each agent lists, switches, and controls only its own tabs — even though every agent shares the same Chrome process, login state, and persistent profile. An owner-scoped browser_close closes only that agent's tabs without stopping the browser.

Owner isolation is an in-process scope, not an authentication boundary. Connections without an owner are administrative and can access all tabs, so do not expose an ownerless HTTP endpoint publicly. Owner setup, per-owner cleanup, and capability-header details are in [INSTALL.md](INSTALL.md).

Managed mode (secure multi-tenant hosting)

Plain multi-agent tabs (above) trust every caller. Managed mode is for a host that runs one browser-rs process for many untrusted tenants — it adds per-owner authentication and keeps the credential database out of browser-rs. (Secret values still pass through browser-rs' memory on their way to Chrome — the broker keeps the lookup/storage logic and long-term credentials out, not the in-flight value itself.)

sequenceDiagram
    participant T as Tenant A (owner=A)
    participant H as Host platform
    participant B as browser-rs
    participant S as Secret broker
    participant C as Chrome

    H->>H: derive capability = HMAC(root, "A")
    H-->>T: hand tenant its capability for owner "A"
    T->>B: request + X-Browser-Capability + X-Browser-Owner: A
    B->>B: verify capability, pin session to owner "A"
    B->>S: transform tool input (e.g. inject a saved password)
    S-->>B: real value, never logged to the client
    B->>C: drive the browser (CDP)
    C-->>B: page output (may contain secrets)
    B->>S: redact output
    S-->>B: safe-to-return text
    B-->>T: result (owner A's tabs only)

• Capability tokens — the host holds one root secret and hands each tenant

an HMAC-SHA256(root, owner) token, so a leaked tenant token can't be used to impersonate another owner or reach /owners (root-only).

• Secret broker — a Unix-socket side-process the host controls. browser-rs

sends tool input through it before acting (e.g. to fill in a real credential the tenant never sees) and tool output through it again before replying (to redact secrets from page text). browser-rs itself never touches the credential database, and any broker error or timeout fails closed. Tools that return page content (browser_snapshot, browser_get_visible_html, browser_get_visible_text, browser_api_request) accept an optional maxLength/maxBytes so the host can raise the internal limit and let the broker redact before the caller-visible truncation is applied.

• Tool allowlist — AB_ALLOWED_TOOLS restricts which browser_* tools a

managed tenant can even see or call.

Required to turn this on: AB_MANAGED=1 plus both AB_HTTP_CAPABILITY and AB_SPAWN_NONCE (the server refuses to start managed without all three). Optional: AB_SECRET_BROKER_SOCKET and AB_SECRET_BROKER_TOKEN together, if you want the redaction broker (see [CLI and environment](#cli-and-environment) for full per-variable semantics). Standalone/self-hosted users can ignore this whole section — it only activates when a host explicitly configures it.

Tools

MCP exposes 67 browser_* tools:

Navigation and inspection: browser_navigate · browser_new_page · browser_snapshot · browser_activate_page · browser_read · browser_get_visible_html · browser_get_visible_text · browser_find · browser_take_screenshot · browser_save_pdf · browser_pages · browser_tabs · browser_switch_page · browser_profile · browser_status

Interaction: browser_click · browser_pointer · browser_wheel · browser_type · browser_cancel_typing · browser_press_key · browser_hover · browser_select_option · browser_fill_form · browser_drag · browser_file_upload · browser_navigate_back · browser_wait_for · browser_resize · browser_evaluate · browser_run_code_unsafe · browser_iframe_click · browser_iframe_fill · browser_iframe_read · browser_close_page · browser_close

Use browser_activate_page({ "page": "p5" }) before automating a background tab whose site throttles lazy loading. It calls CDP Target.activateTarget, retries visibility/focus verification, and uses a process-specific macOS foreground fallback when browser-rs launched Chrome itself. Use browser_wheel({ "page": "p5", "delta_y": 700, "x": 650, "y": 500 }) for a real CDP mouseWheel event instead of DOM window.scrollBy(). Use browser_pointer for right-click/double-click and for an explicit input_route: "dom_event" background compatibility path. Constructed DOM events have isTrusted == false; they are never an automatic fallback from trusted CDP input. browser_type keeps human-like key events for text under 30 characters and uses one atomic CDP Input.insertText command for longer input. browser_cancel_typing stops active per-character typing started with wait: false; text already entered remains, while atomic long-text insertion normally finishes before cancellation.

Network and requests: browser_network_requests · browser_route_block · browser_route_mock · browser_route_clear · browser_network_state_set · browser_api_request

Cookies and storage: browser_cookie_list · browser_cookie_get · browser_cookie_set · browser_cookie_delete · browser_cookie_clear · browser_localstorage_list · browser_localstorage_get · browser_localstorage_set · browser_localstorage_delete · browser_localstorage_clear · browser_sessionstorage_list · browser_sessionstorage_get · browser_sessionstorage_set · browser_sessionstorage_delete · browser_sessionstorage_clear · browser_storage_save · browser_storage_load

Diagnostics and page utilities: browser_console_messages · browser_fingerprint_check · browser_handle_dialog · browser_highlight · browser_hide_highlight · browser_webauthn · browser_claim_page · browser_release_page

CLI and environment

browser-rs                          # stdio MCP transport
browser-rs --port 9321 [options]    # HTTP MCP transport
  --host             HTTP bind host (default 127.0.0.1)
  --user-data-dir    Persistent browser profile directory
  --profile          Alias for --user-data-dir
  --headless               Run headless
  --headed                 Run headful (default)
  --connect      Attach to an existing Chrome
  --stealth                Enable the JS fallback layer

--port enables HTTP mode; without it, the server uses stdio. The equivalent environment variables are AB_HTTP, AB_PROFILE, AB_HEADLESS, AB_CONNECT, AB_STEALTH, and AB_CHROME. AB_HTTP_CAPABILITY protects HTTP/SSE requests with X-Browser-Capability and is required for non-loopback binds.

Managed hosts (see [Managed mode](#managed-mode-secure-multi-tenant-hosting) above) can set:

| Variable | Purpose | |---|---| | AB_MANAGED=1 | Turns on per-owner capability auth for /sse and /mcp | | AB_HTTP_CAPABILITY= | Root secret the host derives per-owner tokens from | | AB_SPAWN_NONCE= | Reported on /health so the host can confirm which process instance is live | | AB_ALLOWED_TOOLS= | Fail-closed allowlist of callable/visible browser_* tool names | | AB_SECRET_BROKER_SOCKET, `AB

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: maestrojeong
• Source: maestrojeong/browser-rs-mcp
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.