Browser Rs

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

ci release 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 A<br/>owner=research"] --> M["browser-rs MCP<br/>one Rust process"]
    B["Agent B<br/>owner=operations"] --> M
    C["Agent C<br/>owner=qa"] --> M
    M --> H["one shared Chrome<br/>persistent profile"]
    H --> T1["research tabs"]
    H --> T2["operations tabs"]
    H --> T3["qa tabs"]

Why browser-rs?

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/ so changes can be tested against current browsers and detectors. See 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. 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.

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.

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.

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 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 <host>            HTTP bind host (default 127.0.0.1)
  --user-data-dir <path>   Persistent browser profile directory
  --profile <path>         Alias for --user-data-dir
  --headless               Run headless
  --headed                 Run headful (default)
  --connect <port|url>     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 above) can set:

Secret-bearing variables (AB_HTTP_CAPABILITY, AB_SPAWN_NONCE, AB_SECRET_BROKER_TOKEN) are removed from the process environment before Chrome launches, so neither Chrome nor its renderers ever see them. AB_MANAGED and AB_ALLOWED_TOOLS are not secrets and are left in place.

These variables are not independent switches — mixing them incorrectly fails startup or silently changes standalone behavior:

• AB_MANAGED=1 requires both AB_HTTP_CAPABILITY and AB_SPAWN_NONCE to also be set, or the server refuses to start.
• AB_HTTP_CAPABILITY set without AB_MANAGED=1 still enables simple capability-header auth on standalone HTTP — it is not managed-mode-only.
• AB_SECRET_BROKER_SOCKET and AB_SECRET_BROKER_TOKEN must be set together; supplying only one fails startup.
• AB_ALLOWED_TOOLS restricts tool discovery/invocation in every mode, including plain stdio — it is not limited to managed hosts.

For --connect, start Chrome with an explicit remote debugging port, then pass that port or its URL:

google-chrome --remote-debugging-port=9222
browser-rs --connect 9222

Development

Requirements: Rust 1.85 or newer, Chrome/Chromium, and Node.js for the optional benchmark scripts.

cargo test --workspace
cargo build --release -p ab-mcp

The bench/ directory contains local detector and browser comparison runners. They are regression tools whose results depend on browser versions, sites, and detectors; they are not compatibility or stealth guarantees:

node bench/run.mjs target/release/browser-rs
node bench/external.mjs target/release/browser-rs
node bench/rebrowser.mjs target/release/browser-rs

See DESIGN.md for architecture and tradeoffs. The source is organized into ab-cdp (CDP transport), ab-browser (browser and page logic), and ab-mcp (the MCP server).

git commit -am "Release vX.Y.Z"
git tag vX.Y.Z
git push origin main vX.Y.Z

FAQ

What is browser-rs? browser-rs is an MCP (Model Context Protocol) browser server — it exposes a real, stealth-oriented Chrome to AI agents as a set of tools (navigate, click, type, snapshot, etc.), so any MCP-compatible client can drive a browser without writing Playwright/Puppeteer glue code itself.

Can multiple AI agents share one browser? Yes — that's the main reason browser-rs exists. One Chrome process and one persistent, logged-in profile are shared across agents; each agent gets its own owner-scoped tab group and can only see/control its own tabs. See Multi-agent tabs.

Is browser-rs a Playwright or Puppeteer alternative? It solves a similar problem — programmatic browser control — but ships as a single ~5.5 MB Rust binary with no Node.js runtime or npm dependency tree, talks to Chrome over raw CDP, and is designed from the start for many agents sharing one browser rather than one script owning one browser instance.

Does browser-rs bypass bot detection? No tool can guarantee that. The default headful mode with a persistent profile and no injected page patches avoids common automation signals, and bench/ has reproducible detector runners to track regressions — but this is not a bypass guarantee. See DESIGN.md.

What is managed mode / multi-tenant hosting? An opt-in mode for a host platform running one browser-rs process for many untrusted tenants, adding per-owner HMAC capability auth, a tool allowlist, and an optional secret broker so long-term credentials never enter browser-rs. See Managed mode.

Related projects

• Negotium — a self-hosted AI agent runtime whose built-in browser tools run on browser-rs.

License

Apache-2.0. See LICENSE.