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`.

`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 `@ref`s

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_id`s 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`.
• 25s Playwright action timeout is an upstream CLI limit, not this wrapper.

License

MIT