agent-browser MCP server

mcp-server-agent-browser

Status: Beta — CLI wrapper is covered by unit tests and a fake-browser stdio smoke test. Cookie restore across a real Chromium restart is still a manual check.

Let LLMs drive a real browser. This MCP server wraps agent-browser (Vercel Labs) so any MCP client can navigate, fill forms, click, snapshot the accessibility tree, and screenshot.

It is not Grok's web_search / open_page. Those fetch documents. This one runs Chromium. Use search to find a URL, then browser_navigate.

Prerequisites

cargo install agent-browser
agent-browser install

Call browser_doctor if anything is missing.

Build

cargo build --release

Binary: target/release/mcp-server-agent-browser

cargo test
./tests/test-stdio.sh

Real Chromium login-restore is not in CI. After a headed login, restart the MCP process and confirm the next browser_navigate is still logged in.

Configuration

MCP client (stdio):

{
  "mcpServers": {
    "agent-browser": {
      "command": "/path/to/mcp-server-agent-browser"
    }
  }
}

Optional TOML at ~/.config/mcp-server-agent-browser/config.toml (see config.example.toml). Missing file uses defaults. Override the path with MCP_AGENT_BROWSER_CONFIG.

Setting	Default	Meaning
headed	false	Show a window. Launch-time only; browser_close first if a headless daemon is already up. Also AGENT_BROWSER_HEADED=1.
persist	true	--session-name <namespace>-<session_id> (default session key default). There's no --namespace CLI flag — namespace is folded into that name instead.
keep_daemon	false	If false, MCP exit runs close so restore state is saved and Chrome does not leak.
namespace	mcp-server	Prefix of the --session-name restore key, isolating this MCP's restore files from a human using the CLI directly.
command_timeout_secs	120	Wrapper timeout. Playwright's own 25s action timeout is left alone (CLI IPC is ~30s).
idle_timeout	1h	Sets AGENT_BROWSER_IDLE_TIMEOUT_MS (env only — there's no --idle-timeout CLI flag). Use "0" with keep_daemon = true.
download_dir	~/Downloads	--download-path. ~ is expanded.
profile	unset	Optional persistent Chrome user-data dir. Not your daily Chrome profile.
encryption_key_file	unset	Sets AGENT_BROWSER_ENCRYPTION_KEY. Restore files are credentials; plaintext unless this is set.
AGENT_BROWSER_PATH	agent-browser	CLI binary.

allowed_domains is optional. Localhost is allowed unless you set a list that excludes it.

What it can do

Same interaction set as before (navigate, click, type, snapshot, screenshot, cookies, eval, CDP, sessions), plus:

• browser_doctor — CLI, config, persist, headed/DISPLAY, daemon guess. Does not launch Chrome.
• browser_get_text pattern — regex over page text with two lines of context.
• browser_wait — load / url / text as well as a selector.

Typical loop:

1. browser_navigate
2. browser_snapshot (-i for interactive)
3. browser_click / browser_fill with @refs
4. browser_screenshot if you need pixels

Persistence

With persist = true (default), each session saves cookies and localStorage on close and on the CLI's autosave interval. State lives under ~/.agent-browser/, namespaced to mcp-server. Isolated session_ids do not share a restore key.

Headed login once, browser_close or exit the MCP, start again. The next navigate should restore that session.

A killed MCP process may leave the daemon running. browser_doctor reports that. Idle shutdown still saves if persist is on.

Limitations

• Chromium via agent-browser (Playwright). No search.
• Headed is ignored until the existing daemon is closed.
• Snap Chromium on Ubuntu can fail to advertise its DevTools port; prefer agent-browser install's browser or executable_path.
• Writes (screenshot, pdf, download) must be relative, under /tmp, or under download_dir.
• Element screenshots take a CSS selector or @ref, plus a trailing :has-text("..."). The selector is checked first, so a miss is an error, not a silent full-viewport shot. Not combinable with full_page.
• 25s Playwright action timeout is an upstream CLI limit, not this wrapper.

License

MIT