Skip to main content
Glama
agent-browser

agent-browser

by NaifAlsultan

agent-browser

An MCP server that gives AI agents a web browser running in the background, built to be hard for sites to tell apart from a person's.

  • Invisible. Google Chrome runs headed on its own virtual display (Xvfb), never on your screen.

  • Isolated. Each agent session gets a fresh, temporary profile, deleted when the session ends.

  • Hard to detect. Real Chrome driven through Patchright, no automation flags, human-like mouse, keyboard and scroll input, and a realistic screen and GPU.

  • Honest about bot checks. Self-clearing challenges are waited out; CAPTCHAs and block pages are reported to the agent, never solved.

Linux only.

WARNING

agent-browser is not a security boundary. Agents browse by writing scripts that run with the server's permissions: files, environment variables, commands. The pages they read can prompt-inject them into writing harmful ones. Run the server in an OS-level sandbox (for example bubblewrap) that hides your files and environment, and don't rely on your MCP client's tool permissions to contain it.

Detection results

Page

Playwright (headless)

agent-browser

bot.sannysoft.com

13 of 31 failed or warned

all passed

BrowserScan

Robot

Normal

CreepJS headless

100%

0%

rebrowser bot detector

6 red

all green

Measured with Chrome 157 and a GPU (scripts/detection-compare.ts). Without a GPU, WebGL falls back to software rendering, which some of these pages flag.

Related MCP server: CloakBrowser MCP

How it works

MCP client ─stdio─▶ agent-browser ─▶ Patchright ─ws─▶ CDP proxy ═pipe═▶ Chrome ─▶ Xvfb
  • One Chrome process per agent session, closed after 15 minutes idle.

  • Chrome is launched directly, with DevTools over a pipe rather than an unauthenticated port.

  • A small CDP proxy adds human-like input and removes Patchright's forced media emulation.

  • The virtual display is protected by an X authority cookie.

Tools

Like browse, one tool does the browsing: agents write Playwright code.

Tool

What it does

run({ code, timeoutMs? })

Run Playwright JavaScript with page, context and state (kept between calls) in scope

close()

Close the session's browser and delete its profile

The instructions tell agents to call close() when they're done browsing, so a session's Chrome doesn't hold memory until the 15-minute idle timeout.

Helpers in run:

  • snapshot({ ref?, maxChars? }): page outline with element refs such as e12, iframes included; password, one-time-code and card values hidden

  • ref(id): a locator for a ref from the latest snapshot

  • screenshot({ fullPage?, ref? }): attach a screenshot to the result

  • log(...) (or console.log): add a line to the result

await page.goto("https://duckduckgo.com/?q=nixos")
return await snapshot()

Results include the return value, the page's title and URL afterwards, new tabs, dialogs (dismissed, except leave-page prompts) and bot challenges. Each session's browser and scripts run in a worker thread: a script still running at timeoutMs (60 s by default) is stopped by ending its worker, which closes that session's browser and leaves other sessions alone.

Sessions are keyed by OpenCode's ai.opencode/sessionID request metadata, so each OpenCode session gets its own browser. Clients that don't send it share one browser per server process, which for stdio clients is usually one per client instance: parallel chats or subagents in it share tabs, cookies and state. If your client sends its own per-conversation ID in _meta, set AGENT_BROWSER_SESSION_META_KEY to that key.

Install

With Nix:

{
  inputs.agent-browser.url = "github:NaifAlsultan/agent-browser";
  # ...
  environment.systemPackages = [ inputs.agent-browser.packages.x86_64-linux.default ];
}

The package includes Chrome and Xvfb. Without Nix, you need Node.js 24+, Google Chrome and Xvfb:

npm ci --omit=dev
node src/main.ts

Then add it to your MCP client, for example OpenCode:

{ "mcp": { "servers": { "agent-browser": { "type": "local", "command": ["agent-browser"] } } } }

Configuration

Variable

Default

AGENT_BROWSER_CHROME

google-chrome-stable

Chrome executable

AGENT_BROWSER_XVFB

Xvfb

Xvfb executable

AGENT_BROWSER_SCREEN

1920x1080

Screen size

AGENT_BROWSER_GPU

auto

on, off or auto (use /dev/dri when available)

AGENT_BROWSER_IDLE_TIMEOUT_MS

900000

Idle time before a session's browser closes

AGENT_BROWSER_HUMAN_INPUT

on

off for faster, more detectable input

AGENT_BROWSER_CHROME_ARGS

Extra Chrome flags

AGENT_BROWSER_TMPDIR

system temp dir

Where profiles go

AGENT_BROWSER_SESSION_META_KEY

ai.opencode/sessionID

Request _meta key that identifies a session

AGENT_BROWSER_DEBUG

off

Verbose logs on stderr

Also: AGENT_BROWSER_ACTION_TIMEOUT_MS, AGENT_BROWSER_NAVIGATION_TIMEOUT_MS, AGENT_BROWSER_CHALLENGE_WAIT_MS, and optional AGENT_BROWSER_XPROP and AGENT_BROWSER_SETPRIV paths (set by the Nix package).

Notes:

  • Chrome applies machine-wide policies from /etc/opt/chrome/policies to every profile, which can make the browser stand out.

  • Chrome's sandbox needs unprivileged user namespaces. Where they're unavailable, pass --no-sandbox in AGENT_BROWSER_CHROME_ARGS.

Development

nix develop
npm ci
npm test                    # unit tests
npm run test:integration    # real Chrome against local pages
npm run typecheck

Credits

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to drive a Chromium-based browser for web research, testing, and automation with Playwright-compatible tools, persistent profiles, proxy matching, extension loading, and humanized input across local or containerized deployments.
      280 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to drive isolated, persistent Chromium browser profiles — each with its own cookies, fingerprint, and proxy — so they can complete real authenticated web workflows such as navigation, clicking, typing, extraction, screenshots, and JavaScript evaluation through a local endpoint.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides a hosted Chromium browser that lets AI agents navigate pages, click, type, hover, drag, fill forms and upload files, inspect network requests and console messages, run Playwright code, and capture screenshots without installing a browser locally. Each session gets an isolated headless browser with token-based authentication.
      MIT