stealth-agent-browser-mcp

A Model Context Protocol (MCP) server that gives AI agents a stealth-grade Chromium browser with a hybrid Accessibility-Object-Model + Set-of-Mark vision interface. Built for Claude, works with any MCP-compatible host.

Stealth first. Uses rebrowser-playwright to patch the Runtime.Enable CDP leak that bypasses playwright-extra-class stealth plugins. Passes modern bot-detection suites (CreepJS, bot.sannysoft.com) where vanilla Playwright fails.
Token-lean by default. browser_snapshot returns Playwright aria snapshot YAML (~2–5 KB) instead of raw HTML (100KB+). Every interactive element carries a [ref=eN] id that actions consume directly — no selectors, no drift.
Hybrid vision when it matters. Ask for mode: "hybrid" and the server overlays numbered red boxes on the screenshot so the model can ground visually (Set-of-Mark prompting, Yang et al.). The ref ids on the image match the ids in the YAML. No parallel numbering scheme to go out of sync.
Readability-based content extraction. browser_scroll_read runs Mozilla Readability through JSDOM and returns clean Markdown — optionally delta-only, so re-reads cost nothing when nothing changed.
Proxy-ready. Per-session proxy auth, useful with residential pools.

Authorized use only. Stealth tooling has legitimate applications (accessibility auditing, your-own-account automation, QA against sites you own or have permission to test). Do not use this server to violate a site's terms of service or applicable law. See SECURITY.md.

Install

npm install -g stealth-agent-browser-mcp
# Chromium binary is fetched automatically on first launch
npx playwright-core install chromium

Or run without install via npx stealth-agent-browser-mcp.

Quickstart (Claude Desktop / Claude Code / Cursor)

Add to your MCP config:

{
  "mcpServers": {
    "stealth-browser": {
      "command": "npx",
      "args": ["-y", "stealth-agent-browser-mcp"],
      "env": {
        "SAB_HEADLESS": "true",
        "SAB_STEALTH_LEVEL": "patched"
      }
    }
  }
}

Restart the host. The agent will see the tools listed below.

Tools

| Tool | Purpose | |---|---| | browser_navigate | Navigate a URL and return a snapshot. | | browser_snapshot | aom (YAML only, cheapest), vision (raw screenshot), or hybrid (YAML + Set-of-Mark screenshot). | | browser_click | Click an element by its [ref=eN]. | | browser_type | Type into an input/textarea by ref. | | browser_select | Choose options in a <select> by ref. | | browser_scroll_read | Scroll and return Readability Markdown (delta-only by default). | | browser_wait_for | Wait for text or a ref to become visible. | | browser_tabs | list / new / close / switch. | | browser_eval | Evaluate a JS expression in the page's MAIN world; JSON result. | | browser_set_proxy | Update proxy config (effective after browser_restart). | | browser_restart | Close + re-open the active browser session with current config. |

All action tools are addressed by the ref emitted in the last AOM snapshot. Refs are Playwright's own aria-ref=eN ids — there is no parallel numbering scheme.

Configuration

All via environment variables:

| Var | Default | Notes | |---|---|---| | SAB_HEADLESS | true | false for a visible window (debugging). | | SAB_STEALTH_LEVEL | patched | off | patched | paranoid. | | SAB_PROXY_SERVER | — | e.g. http://host:port | | SAB_PROXY_USERNAME / SAB_PROXY_PASSWORD | — | | | SAB_USER_DATA_DIR | — | Persistent profile directory (cookies build reputation). | | SAB_DEFAULT_TIMEOUT_MS | 15000 | Per-action timeout. | | SAB_MAX_ANNOTATED | 75 | Max labelled boxes in hybrid mode. | | SAB_VIEWPORT_W / SAB_VIEWPORT_H | 1366 / 768 | | | SAB_LOCALE | en-US | | | SAB_TIMEZONE | America/New_York | | | LOG_LEVEL | info | debug, warn, etc. Always writes to stderr. |

Architecture

src/
├── index.ts         # Entry (stdio)
├── server.ts        # MCP server + tool registration
├── tools.ts         # Tool handlers
├── browser.ts       # Stealth Chromium launcher (rebrowser-playwright)
├── session.ts       # Per-connection browser/context/page state
├── snapshot.ts      # AOM + Set-of-Mark pipeline
├── annotate.ts      # SVG overlay compositing (sharp)
├── reader.ts        # Readability → Markdown
├── fingerprint.ts   # Rotatable UA/viewport/timezone profiles
├── config.ts        # Zod-validated env config
└── logger.ts        # pino → stderr (never stdout)

All logs go to stderr — stdout is reserved for JSON-RPC. Never add console.log.

Benchmarks

npm run bench:stealth launches the configured browser against public bot-detection test pages (bot.sannysoft.com, CreepJS, pixelscan, BrowserLeaks WebRTC) and reports pass/fail. These are the same harnesses used by the rebrowser-patches and Patchright projects — see rebrowser-bot-detector for the reference suite.

Typical local-fixture test run (see test/):

| Test | Result | |---|---| | AOM YAML contains refs for all interactive elements | ✓ | | hybrid mode returns PNG + YAML, refs match | ✓ | | click/type by ref produces expected DOM change | ✓ | | Readability extracts article to Markdown | ✓ | | Delta-only scroll returns (no readable content change) on repeat | ✓ |

Comparison

| | stealth-agent-browser-mcp | playwright-mcp | browser-use MCP | computer use | |---|---|---|---|---| | CDP-level stealth (Cloudflare/DataDome) | ✓ | ✗ | partial | ✗ | | Accessibility-tree snapshots | ✓ | ✓ | ✓ | ✗ | | Set-of-Mark vision (ref-labeled screenshot) | ✓ | ✗ | ✗ | pure vision | | Readability-based scroll-and-read | ✓ | ✗ | ✗ | ✗ | | Token-lean by default | ✓ | ✓ | ✗ | ✗ | | Bundled agent loop | ✗ (host's model drives) | ✗ | ✓ | ✗ |

Development

npm install
npx playwright-core install chromium
npm run build
npm test

Contributing

See CONTRIBUTING.md. All contributions under Apache-2.0.

License

Apache-2.0

MCP Servers