Skip to main content
Glama
README.md
# 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](https://github.com/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.

## Run the server

Requires [Bun](https://bun.sh).

```sh
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:

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

```sh
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:

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

Any MCP client that speaks Streamable HTTP:

```json
{
  "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

```sh
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](LICENSE).