# Agent Browser MCP server

> Lets an AI agent drive a self-hosted Chrome session that a human can watch and take over through a live noVNC view.

- Repository: https://github.com/AetherAI3/agent-browser
- Page: https://hostedmcp.org/servers/aetherai3/agent-browser
- Transport: stdio
- Stars: 14
- License: Apache-2.0
- Latest version: 0.2.2

## Install

### Claude Code

```sh
claude mcp add --env 'AGENT_BROWSER_CONTROLLER_TOKEN=<YOUR_AGENT_BROWSER_CONTROLLER_TOKEN>' --env 'AGENT_BROWSER_OBSERVER_TOKEN=<YOUR_AGENT_BROWSER_OBSERVER_TOKEN>' agent-browser -- npx -y aether-browser
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "agent-browser": {
      "command": "npx",
      "args": [
        "-y",
        "aether-browser"
      ],
      "env": {
        "AGENT_BROWSER_CONTROLLER_TOKEN": "<YOUR_AGENT_BROWSER_CONTROLLER_TOKEN>",
        "AGENT_BROWSER_OBSERVER_TOKEN": "<YOUR_AGENT_BROWSER_OBSERVER_TOKEN>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "agent-browser": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "aether-browser"
      ],
      "env": {
        "AGENT_BROWSER_CONTROLLER_TOKEN": "<YOUR_AGENT_BROWSER_CONTROLLER_TOKEN>",
        "AGENT_BROWSER_OBSERVER_TOKEN": "<YOUR_AGENT_BROWSER_OBSERVER_TOKEN>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"agent-browser","type":"stdio","command":"npx","args":["-y","aether-browser"],"env":{"AGENT_BROWSER_CONTROLLER_TOKEN":"<YOUR_AGENT_BROWSER_CONTROLLER_TOKEN>","AGENT_BROWSER_OBSERVER_TOKEN":"<YOUR_AGENT_BROWSER_OBSERVER_TOKEN>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "agent-browser": {
      "command": "npx",
      "args": [
        "-y",
        "aether-browser"
      ],
      "env": {
        "AGENT_BROWSER_CONTROLLER_TOKEN": "<YOUR_AGENT_BROWSER_CONTROLLER_TOKEN>",
        "AGENT_BROWSER_OBSERVER_TOKEN": "<YOUR_AGENT_BROWSER_OBSERVER_TOKEN>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add agent-browser --env 'AGENT_BROWSER_CONTROLLER_TOKEN=<YOUR_AGENT_BROWSER_CONTROLLER_TOKEN>' --env 'AGENT_BROWSER_CONTROLLER_TOKEN=<YOUR_AGENT_BROWSER_CONTROLLER_TOKEN>' --env 'AGENT_BROWSER_OBSERVER_TOKEN=<YOUR_AGENT_BROWSER_OBSERVER_TOKEN>' --env 'AGENT_BROWSER_OBSERVER_TOKEN=<YOUR_AGENT_BROWSER_OBSERVER_TOKEN>' -- npx -y aether-browser
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.agent-browser]
command = "npx"
args = ["-y", "aether-browser"]

[mcp_servers.agent-browser.env]
AGENT_BROWSER_CONTROLLER_TOKEN = "<YOUR_AGENT_BROWSER_CONTROLLER_TOKEN>"
AGENT_BROWSER_OBSERVER_TOKEN = "<YOUR_AGENT_BROWSER_OBSERVER_TOKEN>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'AGENT_BROWSER_CONTROLLER_TOKEN=<YOUR_AGENT_BROWSER_CONTROLLER_TOKEN>' -e 'AGENT_BROWSER_CONTROLLER_TOKEN=<YOUR_AGENT_BROWSER_CONTROLLER_TOKEN>' -e 'AGENT_BROWSER_OBSERVER_TOKEN=<YOUR_AGENT_BROWSER_OBSERVER_TOKEN>' -e 'AGENT_BROWSER_OBSERVER_TOKEN=<YOUR_AGENT_BROWSER_OBSERVER_TOKEN>' agent-browser npx -- -y aether-browser
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "agent-browser": {
      "command": "npx",
      "args": [
        "-y",
        "aether-browser"
      ],
      "env": {
        "AGENT_BROWSER_CONTROLLER_TOKEN": "<YOUR_AGENT_BROWSER_CONTROLLER_TOKEN>",
        "AGENT_BROWSER_OBSERVER_TOKEN": "<YOUR_AGENT_BROWSER_OBSERVER_TOKEN>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `AGENT_BROWSER_CONTROLLER_TOKEN` | no | yes | Controller token, if the server runs authenticated. |
| `AGENT_BROWSER_CONTROLLER_TOKEN` | no | yes | Controller token, if the server runs authenticated. |
| `AGENT_BROWSER_OBSERVER_TOKEN` | no | yes | Observer token for read-only health and snapshot calls. |
| `AGENT_BROWSER_OBSERVER_TOKEN` | no | yes | Observer token for read-only health and snapshot calls. |
| `AGENT_BROWSER_URL` | no | no | Base URL of your Agent Browser server. Defaults to http://127.0.0.1:8092. |
| `AGENT_BROWSER_URL` | no | no | Base URL of your Agent Browser server. Defaults to http://127.0.0.1:8092. |
| `SESSION_ID` | no | no |  |

## FAQ

### How do I add Agent Browser to an MCP client?

Run the one-line add command with npx, or add an mcpServers entry pointing at npx aether-browser mcp. It works with Claude Code, Claude Desktop, Cursor, and Windsurf.

### What tools does the MCP server expose?

It provides nine browser tools covering open, navigate, read, click, type, press, scroll, status, and close. Each response repeats the live view URL so you know where to look.

### Can a human take over the browser when the agent is stuck?

Yes, the live view shows the same Chrome session the agent uses, so a human can step in and then hand control back. The server instructs the model to ask for a takeover at logins, payments, or 2FA prompts.

### How do I start the runtime?

Run docker compose up --build on Docker Engine for Linux with Compose v2. The first build takes several minutes while it installs Python and Chrome.

### Where can I watch the agent's browser session?

Open the noVNC live view on local loopback port 6080 after the runtime is healthy. The same URL is returned when a session is created.