fuse-browser

Agentic browser for AI agents — an MCP server and CLI on top of Patchright (stealth) with a Playwright fallback.

It gives an LLM a real browser with: per-country identity (locale/currency/timezone/geo), stealth, self-healing actions, an accessibility-style snapshot with stable refs, multi-step plans, semantic waits, structured extraction, and human guardrails for payments and bookings. Because it drives a real Chromium, it reads Next.js / SPA pages after hydration — not just static HTML.

TypeScript port of the original Python fusengine-browser-agent, redesigned around the official MCP SDK with a persistent session model, image-content screenshots, and a swappable engine layer (Playwright / Patchright / CDP attach).

Requirements

• Node.js >= 20 (runtime). Bun is the dev toolchain.
• A Chromium build for the bundled engine:

npx patchright install chromium   # stealth engine (default)
npx playwright install chromium    # fallback engine

Three ways to get a browser

browser_connect launches an installed browser with a remote-debugging port and attaches to it automatically. Verified end-to-end against Dia (Chromium 148).

CLI

# One-shot probe of a real page
npx fuse-browser probe https://example.com --extract-prices --observe-visual

# Hotels with country identity, proxy routing, replay
npx fuse-browser probe 'https://www.booking.com/searchresults.html?ss=Tokyo' \
  --country JP --proxy-map proxies.json --replay --auto-consent --extract-prices

# Use the installed Chrome
npx fuse-browser probe https://example.com --channel chrome

Sensitive actions (pay, book, checkout, confirm, …) are blocked unless --approved is passed.

MCP server

{
  "mcpServers": {
    "fuse-browser": { "command": "npx", "args": ["-y", "@fusengine/browser-mcp"] }
  }
}

Default browser via env

By default the server uses the bundled stealth Chromium. To pin a different default for every tool call (without the agent specifying it each time), set FUSE_* env vars in the MCP config — an explicit per-call argument still wins:

{
  "mcpServers": {
    "fuse-browser": {
      "command": "npx",
      "args": ["-y", "@fusengine/browser-mcp"],
      "env": { "FUSE_CHANNEL": "chrome", "FUSE_CDP_ENDPOINT": "http://localhost:9222" }
    }
  }
}

Supported: FUSE_ENGINE, FUSE_CHANNEL, FUSE_CDP_ENDPOINT, FUSE_EXECUTABLE_PATH, FUSE_HEADLESS, FUSE_COUNTRY, FUSE_CURRENCY, FUSE_USER_DATA_DIR, FUSE_STORAGE_STATE, FUSE_OUTPUT_DIR.

Tools (23)

Key agentic patterns:

• browser_snapshot → browser_act — snapshot tags each interactive element with a stable ref; act on a ref deterministically (or by text fallback). browser_act returns a diff of what changed (added/removed/text/url).
• browser_wait_for — wait on a condition (text / selector / gone / urlContains), not a fixed delay.
• browser_run — execute an ordered plan (navigate/act/wait/extract) in one call, stopping at the first failure. Guardrails apply to the whole plan.

A runs resource exposes the JSON reports and screenshots written under runs/.

Library

import { BrowserAgent } from "fuse-browser";

const agent = new BrowserAgent({ countryCode: "CH", engine: "patchright" });
const report = await agent.probe("https://example.com", { extractPrices: true });

Development

bun install
bun run typecheck       # tsc strict, no emit
bun test tests/unit     # pure unit tests
bun run test:integration # real headless Chromium + MCP in-process
bun run build           # emit dist/ (JS + .d.ts)

CI (.github/workflows/ci.yml) runs typecheck + unit + build + integration on every push.

Output & data location

Artifacts (reports, screenshots, site-memory, replay) are written outside the repo by default:

• nested under the detected host-agent config dir when present — .claude/fuse-browser/, .cursor/, .codex/, .windsurf/, .gemini/, .continue/, .junie/, .github/;
• otherwise ~/.fuse-browser/.

Override per run with outputDir (library / MCP arg) or --output-dir (CLI). Cookies (storageStatePath) and the Chromium profile (userDataDir) are separate paths you set explicitly.

⚠️ Reports and storage-state files contain page content, screenshots and session cookies in clear text — never commit them. The bundled .gitignore already excludes the defaults.

Guardrails & limits

• No payment/booking/ticketing/card action without explicit human approval.
• Passwords masked in reports; proxy credentials redacted.
• CAPTCHA / 2FA: detection by default; an opt-in solver is available for authorized testing only — see Resilience & captcha.
• Concurrent sessions are capped (maxSessions, default 8) to avoid OOM.
• CDP attach: the remote-debugging port is a local attack surface — use a dedicated profile.

Resilience & captcha

• Navigation retry (on by default): transient failures and HTTP 429/502/503/504 are retried with full-jitter exponential backoff, honoring Retry-After. Tune via retry: { maxAttempts, baseMs, capMs, throttleMs } (defaults 3 / 300 / 10000 / 0). throttleMs enforces a minimum gap between hits on the same host.
• Captcha solver (off by default, opt-in): set solveCaptcha: true on a probe and provide captcha: { provider, apiKey } (2captcha | anticaptcha | capmonster). It solves reCAPTCHA v2 / Cloudflare Turnstile via the provider's API; the result is reported as captcha: { attempted, solved, kind, provider, reason }. Failures are reported, never thrown.

Disclaimer

Provided as-is under MIT, with no warranty. fuse-browser is a neutral, dual-use automation tool. You alone are responsible for how you use it and for complying with applicable law, the target sites' Terms of Service, robots.txt, and data-protection rules (e.g. GDPR). The opt-in captcha solver is intended for authorized testing only — on systems you own or are explicitly permitted to test.

License

MIT