What agent-browser does
The agent-browser MCP server gives an MCP client control of Chromium through Vercel Labs' agent-browser command-line tool. It is intended for live browser automation: an agent can open URLs, inspect page structure, interact with controls, and capture visual output. This differs from web-search or page-fetching tools, which retrieve documents without operating a browser.
The available interaction set includes navigation, clicking, typing and form filling, accessibility-tree snapshots, screenshots, cookies, JavaScript evaluation, Chrome DevTools Protocol access, and sessions. Additional wrapper capabilities include browser diagnostics, regular-expression text matching with surrounding context, and waiting for page load, URL, text, or selector conditions.
How it works
The MCP process launches or communicates with an agent-browser Chromium daemon. A typical agent workflow is to navigate first, request an interactive snapshot to obtain element references, use those references for clicks or form filling, and take a screenshot when pixel-level output is needed.
Persistence is enabled by default. Each session_id receives its own restore key, and cookies plus local storage are saved when the browser closes and during the CLI's autosave process. A later run can restore that session. Restore data is stored below ~/.agent-browser/ in the mcp-server namespace. An encryption key file can be configured because the restore files contain credentials.
The browser_doctor tool checks the CLI, configuration, persistence settings, headed-mode environment, and likely daemon state without launching Chrome. If the MCP process is killed, the daemon may remain active; the diagnostic tool can report this condition.
Setup and configuration
Install the CLI and its browser before building or running the MCP server:
cargo install agent-browser
agent-browser install
cargo build --release
The resulting binary is target/release/mcp-server-agent-browser. Configure an MCP client to start that binary over stdio. The optional TOML file is located at ~/.config/mcp-server-agent-browser/config.toml; set MCP_AGENT_BROWSER_CONFIG to use another path.
Configuration controls headed mode, persistence, daemon lifetime, namespace isolation, wrapper timeouts, idle shutdown, download location, a separate Chrome profile, and encryption. Defaults include headless operation, persistence enabled, a one-hour idle timeout, and ~/Downloads for downloads. AGENT_BROWSER_HEADED=1 enables headed mode, while AGENT_BROWSER_PATH selects a different CLI binary. Headed mode takes effect at launch, so an existing headless daemon must be closed first.
Tools and capabilities
The agent-browser MCP server supports tools for:
- Navigating pages and waiting for page conditions
- Inspecting accessibility snapshots and locating interactive references
- Clicking, typing, and filling forms
- Reading page text, including regex matches with two lines of context
- Taking screenshots
- Managing cookies and browser sessions
- Evaluating JavaScript and using CDP operations
- Checking installation and daemon configuration with
browser_doctor
Limitations and notes
The agent-browser MCP server uses Chromium through Playwright and does not provide web search. Playwright's upstream action timeout is 25 seconds; the wrapper's command timeout is configurable separately. Headed operation is ignored while an existing daemon is running.
Screenshot, PDF, and download destinations must be relative paths, paths under /tmp, or paths inside the configured download directory. Snap Chromium on Ubuntu may fail to expose its DevTools port; the browser installed by agent-browser install, or an explicit executable path, is preferred in that case.
The project is beta. Unit tests cover the CLI wrapper, and a fake-browser stdio smoke test is available, but real Chromium login restoration after a restart requires manual verification. The server is licensed under MIT.
