Skip to main content
Glama

browser-agent

An MCP server that lets AI agents drive your real browser through a Chrome extension.

agent ──MCP (HTTP)──▶ browser-agent server ◀──WebSocket── Chrome extension ──▶ your tabs
  • The extension connects out to the server, so the server can run anywhere: your laptop, a VPS, or a PaaS.

  • Agents keep their tabs in tab groups named for their task: browser_navigate takes a group name for a new tab, and tabs a page opens join its group.

  • Agents read pages as a compact outline with [eN] refs. After every action they get a diff of what changed.

  • One browser at a time. If a second extension connects, it replaces the first.

Forked from qwadrox/bb-plugin-desktop-browser-agent. The CUA driver, the bb plugin parts, native messaging and most of the guardrails were removed.

No guardrails. Anyone who has the MCP URL can do anything in your browser that you can, including run JavaScript in your logged-in sessions. Keep the SECRET secret.

Tools

Tool

What it does

browser_tabs

List the open tabs with ids, titles, URLs and groups

browser_navigate

Open a URL. With no tab_id it opens a new tab in the tab group named by group. Also takes back, forward and reload

browser_read

Read the page as an outline with refs; interactive, query and scope narrow it. Controls with no name get a hint (icon, test id)

browser_click

Click a ref or an x/y point with trusted mouse input: right/middle button, double/triple click, modifiers, hover, and drag (including HTML drag and drop)

browser_upload

Give files to a file input, or drop them on an element, from a path on the browser's computer, a URL, or base64 data

browser_logs

Console messages, page errors and network requests, recorded from the first call on a tab; request_id gives a request's headers and bodies

browser_fill

Fill text fields, selects and checkboxes in one call

browser_key

Press a key or a combo (Enter, Control+A, …)

browser_eval

Run an async JS function body, in an isolated world (default) or the page's main world; returns its JSON value

browser_screenshot

Take a JPEG of the tab or of one ref

browser_close

Close a tab

If the page re-rendered an element, so its ref is gone, actions use the one element with the same role and name and say so.

Actions take an optional wait_for text to wait for after the action. Dialogs (alert, confirm, prompt) are accepted automatically and reported in the result.

Related MCP server: tablaze

Run the server

Requires Bun.

bun install
SECRET=$(openssl rand -hex 16) PORT=3000 bun start

Env

Default

PORT

3000

SECRET

(none)

Path secret. The endpoints become /mcp/<SECRET> and /ext/<SECRET>. Without it they're /mcp and /ext, open to anyone who can reach the server

Endpoints:

  • POST /mcp/<SECRET>?agent=<name>: stateless Streamable HTTP MCP. agent (or an X-Agent-Id header) is optional: it's the group name when the agent doesn't pass group. The default is Agent.

  • GET /ext/<SECRET>: the extension's WebSocket.

  • GET /healthz: {"ok":true,"browser":{…} | null}.

To run it with Docker:

docker build -t browser-agent .
docker run -p 3000:3000 -e SECRET=... browser-agent

Behind a reverse proxy, make sure the proxy passes WebSocket upgrades through on /ext/…. Tool calls can take up to 90 s, so allow long requests.

Install the extension

bun run build:extension

In Chrome (116+) or Brave, open chrome://extensions (brave://extensions), turn on Developer mode, click Load unpacked and pick extension/dist.

Click the extension's icon, paste the server's extension URL, https://<host>/ext/<SECRET> (or wss://…), and press Save. The popup shows whether it is connected. It reconnects on its own.

To bake a default URL into a build instead (the popup still overrides it): SERVER_URL=wss://<host>/ext/<SECRET> bun run build:extension.

While it is driving a tab, Chrome shows a "started debugging this browser" bar.

Connect an agent

Claude Code:

claude mcp add --transport http browser "https://browser.example.com/mcp/<SECRET>?agent=claude"

Any MCP client that speaks Streamable HTTP:

{
  "mcpServers": {
    "browser": { "type": "http", "url": "https://browser.example.com/mcp/<SECRET>?agent=research" }
  }
}

Agents name their own groups per task. agent= only sets the fallback name. Agents can still see and use every tab.

Develop

bun run dev          # server with --watch
bun run typecheck
CHROMIUM="<Chrome for Testing binary>" bun run test:e2e

The end-to-end test starts the server, builds the extension against it, loads the extension into headless Chrome for Testing, and drives it over MCP. Branded Chrome ignores --load-extension, so get Chrome for Testing with npx @puppeteer/browsers install chrome@stable.

Layout:

  • server/src: Bun server (server.ts), extension bridge (bridge.ts), MCP tool definitions (tools.ts)

  • extension/src: service worker (background.ts), popup (popup.ts), in-page functions (page.ts, outline.ts), wire protocol (shared.ts)

License

MIT. 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
      A
      quality
      B
      maintenance
      Enables AI agents to drive a Chromium browser through MCP, with persistent sessions, compact page snapshots, guarded actions, batched operations, and explicit result verification.
      16
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to see and control the user's real Chrome/Brave/Edge profile over MCP, so they can read pages, click, type, take screenshots, audit layouts, debug CSS, and scrape paginated or infinite-scroll data. Because it drives the normal browser via the DevTools protocol with real input events, it works on modern JavaScript apps and on sites where the user is logged in.
      17 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to drive a live, persistent self-hosted Chromium session over MCP, running browser actions via Playwright/CDP, capturing page snapshots, screenshots and videos, and managing uploads and downloads in the same tabs and signed-in accounts a human user can take over at any time.
      28 npm
      Apache 2.0