Skip to main content
Glama

Agent Browser Use

Let AI coding agents drive a real browser over MCP, while you watch every step live in a web page and can take over at any time.

Agent Browser Use is a single Go binary that runs one headless Chrome on your machine and exposes it as a set of Model Context Protocol tools in the style of Playwright MCP. Any MCP-capable agent (Claude Code, Codex, OpenCode, Pi, Cursor, VS Code…) can navigate, read the page, click, type and log in for you, while a web viewer shows the agent's cursor, the element it is acting on, and a log of every step.

Demo

https://github.com/user-attachments/assets/19edb4dd-3e3f-45e3-8809-b27a6c31be58

Demo

Related MCP server: Chrome Bridge

Screenshots

Features

  • Playwright-style MCP tools — browser_snapshot returns an accessibility outline with a ref for every element, and the action tools (click, type, scroll, drag, select…) use those refs.

  • Live viewer — watch the page stream in your browser, with the agent's cursor, captions and chat log.

  • Shared browser room — you and the agent use the same Chrome; take control at any time, or block the agent.

  • Pick an element — click the pick button, point at anything on the page and get a short code (e.g. el-1d2a). Paste it to your coding agent, which looks the element up with browser_get_element and can act on it right away.

  • Record a flow — press the red record button, do a task in the browser, then stop. You get a flow id (e.g. flow-3fa9c1): paste just the id to your agent, which looks it up with browser_get_flow and replays it with browser_run_flow (repeat it N times, or change what gets typed with inputs) or adapts it to what you ask. The Flows tab in the sidebar lists your flows: view and edit their steps, rename, replay, export/import or delete them. Passwords are never stored: the agent must be given them at replay time.

  • Persistent logins — cookies live in a profile folder, so you sign in once and the agent reuses the session.

  • No heavy dependencies — no Docker, X server or video encoder needed. Docker is available if you prefer it.

Quick start

  1. Download the project and start the server (requires Go 1.22+ and Chrome/Chromium, or just Docker):

    git clone https://github.com/cavaldos/agent-browser-use.git
    cd agent-browser-use
    make run            # starts the server on port 3000

    Or run it with Docker: make docker.

  2. The server listens on port 3000:

Keep the server running while you use your agents. Other commands: make build (builds bin/agent-browser-use), make docker-logs, make docker-stop. Options: PORT=8080, HOST=0.0.0.0, ARGS="-agent-speed 1".

Own IP via Cloudflare WARP (browser only): the globe chip in the header always shows the agent browser's public IP; its switch sends the browser through Cloudflare WARP. WARP runs inside the app (userspace WireGuard, no network interface, no route changes), so your computer keeps its own IP. The first time you switch it on, the app signs up a free WARP account and keeps it in warp.json next to the profile folder (private key, don't share it). To use your own SOCKS5 proxy instead, pass -proxy socks5://host:port (or AGENT_BROWSER_USE_PROXY); make docker-warp does that with a WARP container. DNS and WebRTC also go through the tunnel, so the real IP does not leak.

Install

macOS / Linux (Windows: run it inside WSL)

curl -fsSL https://raw.githubusercontent.com/cavaldos/agent-browser-use/main/scripts/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/cavaldos/agent-browser-use/main/scripts/install.ps1 | iex

Then run agent-browser-use. Viewer: http://localhost:3000, MCP endpoint: http://localhost:3000/mcp.

Uninstall: rm ~/.local/bin/agent-browser-use (Windows: Remove-Item -Recurse $env:LOCALAPPDATA\agent-browser-use)

Prefer Docker or need more options? See docs/INSTALL.md.

Browser engine

# macOS
brew install --cask chromium
# Debian / Ubuntu
sudo apt install -y chromium
# Fedora
sudo dnf install -y chromium
# Windows (PowerShell)
winget install Hibbiki.Chromium

Connecting a coding agent (MCP)

Start the server with a password (./agent-browser-use -pw your-password), then point your agent at http://localhost:3000/mcp. New to MCP, or want the stdio mode? Read the general guide.

No password? Start the server without -pw, then delete the Authorization header / token lines in the snippets below.

Claude Code

claude mcp add --transport http agent-browser http://localhost:3000/mcp --header "Authorization: Bearer your-password"

Or in a project .mcp.json:

{
  "mcpServers": {
    "agent-browser": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": { "Authorization": "Bearer your-password" }
    }
  }
}

Check it with claude mcp list or /mcp.

Codex (OpenAI)

~/.codex/config.toml (or .codex/config.toml in a trusted project). The password stays in an environment variable so it isn't written in the file:

[mcp_servers.agent-browser]
url = "http://localhost:3000/mcp"
bearer_token_env_var = "AGENT_BROWSER_USE_PASSWORD"
export AGENT_BROWSER_USE_PASSWORD=your-password

Restart Codex after editing the file.

OpenCode

opencode.json (project root or global config):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "agent-browser": {
      "type": "remote",
      "url": "http://localhost:3000/mcp",
      "enabled": true,
      "headers": { "Authorization": "Bearer your-password" }
    }
  }
}

Pi

MCP is not part of every Pi install; it is often added through an extension such as the community pi-mcp-adapter. Once MCP is enabled, use the common mcpServers format:

{
  "mcpServers": {
    "agent-browser": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": { "Authorization": "Bearer your-password" }
    }
  }
}

Other agents

Cursor, VS Code, Windsurf, Gemini CLI, Cline, Zed, Claude Desktop and more: docs/MCP-CLIENTS.md.

Verify the connection

Ask your agent something like:

Go to news.ycombinator.com, open the top story and summarize it.

Then open http://localhost:3000 to watch the agent work.

Available tools

Tool

What it does

browser_navigate / browser_navigate_back / browser_navigate_forward / browser_reload

Open a URL (non-URL text is searched on Google), or move through history

browser_snapshot

Accessibility outline of the page, with a ref for each actionable element

browser_click / browser_hover / browser_type / browser_press_key

Click, hover, type into a field, press keys and shortcuts

browser_select_option / browser_scroll / browser_drag

Pick <select> options, scroll, drag and drop

browser_wait_for / browser_wait_for_change

Wait for text, or for the page to change on its own

browser_take_screenshot / browser_evaluate

Screenshot the tab, or run JavaScript in the page

browser_tabs / browser_say

Manage tabs, or show a message to the people watching

browser_console_messages / browser_network_requests

Console output, exceptions and network requests (status, headers, response body). Action results also list new console errors and failed requests

browser_downloads / browser_file_upload

Wait for and read downloaded files; fill <input type=file> from the upload folder

browser_cookies / browser_storage / browser_state

Read and change cookies and localStorage/sessionStorage; save and restore a whole login session by name

browser_snapshot_diff

Only what changed on the page since the last snapshot or a named baseline

browser_emulate

Phone/tablet presets, screen size, pixel ratio, touch, user agent, locale, time zone, dark mode, GPS location, network speed

browser_get_flow

Read a flow a person recorded (by its id, e.g. flow-3fa9c1), or list all flows

browser_run_flow

Replay a recorded flow, optionally several times, with changed inputs (inputs)

Recorded flows

Record a task once, then let the agent repeat it or adapt it:

  1. Press the red record button under the screen and use the browser as usual (clicks, typing, choices in lists, keys, links, tabs).

  2. Press Stop & save. You get an id such as flow-3fa9c1.

  3. Paste the id to your agent with what you want, e.g. "flow-3fa9c1, do it for these three names". Alone, the id replays the flow once.

The agent finds the flow with browser_get_flow, then replays it with browser_run_flow or follows its steps when the job needs changes. Actions the agent takes itself are not recorded.

  • Passwords are never stored. A password step needs its value passed in inputs at replay time, or a saved login (browser_state).

  • Flows tab (sidebar): list, search, rename, view and edit steps, remove steps, replay from the viewer, export and import as .json, delete.

  • Flows are saved in the flows/ folder next to the browser profile (change it with -flows <folder>).

  • Not recorded: hover-only menus, scrolling, and anything inside an iframe.

See docs/GUIDE.md for the full tool reference, options, the shared browser room, security and limitations.

Security

  • Uploads only read from the upload folder (and the download folder), never from other places on the machine. Saved sessions (states/) contain cookies: treat them like passwords.

  • The shared browser keeps the cookies of every account you log into. The agent can read any open page and run JavaScript in it, so only log into accounts you are happy for the agent to use.

  • By default /mcp only accepts connections from the local machine, and it rejects requests from other websites.

  • Without -pw, anyone who can reach port 3000 can open the viewer and drive the browser. Keep it on a trusted network, or set a password.

Project layout

app/        Go source (MCP server, browser control, agent, web UI in static/)
docker/     Dockerfile and entrypoint
scripts/    run / build / docker scripts
docs/       full guide and images
bin/        built binary (make build)

Documentation

Star History

Star History Chart

License

See LICENSE.

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
      B
      maintenance
      single-binary MCP server that gives AI agents a browser. 66 tools for navigation, form filling, data extraction, screenshots, and DOM diffing — built on pure Chrome DevTools Protocol.
      14
      MIT
    • A
      license
      A
      quality
      A
      maintenance
      MCP server + Chrome extension that drive the user's real, logged-in Chrome over a local WebSocket. 59 token-efficient web-dev tools: compact element refs instead of screenshots, server-side table filtering, visual regression, accessibility/SEO/security audits, network mocking. Also runs on ChromeOS/Crostini.
      69
      1,144 npm
      7
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP server that lets agents drive your real Chrome browser with existing logins and sessions via an outbound-only WebSocket extension. It exposes Playwright-compatible browser tools for navigation, clicking, typing, and snapshots.
      1
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to drive a real Chrome instance over the Chrome DevTools Protocol — opening and navigating tabs, reading compact YAML page outlines with refs, clicking, typing, scrolling, screenshotting, and evaluating scripts — with no browser extension or installed dependencies. It also audits pages for horizontal overflow and WCAG AA contrast, available both as an MCP tool and as a CI-friendly CLI.
      15 npm
      MIT