# AI Browser MCP server

> An Electron-based browser that allows AI agents to navigate and interact with web pages using a semantic accessibility tree instead of screenshots.

- Repository: https://github.com/Glittering/ai-browser
- Page: https://hostedmcp.org/servers/glittering/ai-browser
- Transport: stdio
- Stars: 5
- License: MIT
- Latest version: 2.5.5

## Install

### Claude Code

```sh
claude mcp add ai-browser -- npx -y @glittering0717/ai-browser
```

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

```json
{
  "mcpServers": {
    "ai-browser": {
      "command": "npx",
      "args": [
        "-y",
        "@glittering0717/ai-browser"
      ]
    }
  }
}
```

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

```json
{
  "servers": {
    "ai-browser": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@glittering0717/ai-browser"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"ai-browser","type":"stdio","command":"npx","args":["-y","@glittering0717/ai-browser"]}'
```

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

```json
{
  "mcpServers": {
    "ai-browser": {
      "command": "npx",
      "args": [
        "-y",
        "@glittering0717/ai-browser"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add ai-browser -- npx -y @glittering0717/ai-browser
```

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

```toml
[mcp_servers.ai-browser]
command = "npx"
args = ["-y", "@glittering0717/ai-browser"]
```

### Gemini CLI

```sh
gemini mcp add -s user ai-browser npx -- -y @glittering0717/ai-browser
```

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

```json
{
  "mcpServers": {
    "ai-browser": {
      "command": "npx",
      "args": [
        "-y",
        "@glittering0717/ai-browser"
      ]
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `AI_BROWSER_FOCUS` | no | no |  |
| `AI_BROWSER_INPUT_FOCUS` | no | no |  |
| `AI_BROWSER_PORT` | no | no |  |
| `AI_BROWSER_START_HIDDEN` | no | no |  |
| `AI_BROWSER_USER_DATA` | no | no |  |
| `ELECTRON_MIRROR` | no | no |  |

## Tools (17)

- `browse_navigate`: Navigate your tab to a URL. Returns at the requested milestone (default: DOM ready) — it does not wait for load, which SPAs often never fire.
- `browse_get_tree`: Return the page semantic tree (roles, labels, actions, bounds). Root adds editors (primary) when 2+ editable. (read-only)
- `browse_act`: Act on a data-ai-id element. type appends at caret, setContent replaces all. page_changed:false = dispatched but page unchanged (wrapper).
- `browse_evaluate`: Run a JS expression in the page context and return its value. Promises are awaited (async IIFEs return their resolved value, not {}).
- `browse_scroll`: Scroll the page or an element into view.
- `browse_wait`: Poll the page until a condition holds or timeout. Conditions: button_enabled, modal_appeared, text_contains, url_contains. (read-only)
- `browse_auth_state`: Is this tab still logged in, or bounced to a login wall? auth_wall.detected=true means stop debugging and re-authenticate first. logged_in is heuristic; auth_wall is the signal to trust. (read-only)
- `browse_screenshot`: Screenshot the viewport (base64). Use FIRST when an action misbehaves: the tree cannot show overlays, canvas, occlusion or glitches. Warns about visible password inputs. (read-only)
- `browse_tabs`: Tabs: list/new/close/switch/window. Yours are grouped and capped. switch = default; add show:true. new never steals the view unless show:true. window = hide/show.
- `browse_network`: Query captured HTTP requests: list/get/clear/configure. Captures headers and POST bodies; sensitive headers redacted. Each op reads its own group: filters / include / body_offset / configure.
- `browse_canvas`: Read <canvas> via captured draw calls (not pixels): list, read texts/regions, configure, or capture a PNG fallback. 2D text comes from fillText, so no OCR; WebGL is opaque.
- `browse_diff`: Prove an action changed the page: snapshot a baseline, then diff to get added/removed/changed paths with before/after values. Success is not evidence. (read-only)
- `browse_capabilities`: Probe how to operate a page: DOM vs canvas, iframes, app objects on window, JSON endpoints, plus a plan. deep=true also probes closure-hidden models (canvas editors that report none). (read-only)
- `browse_repaint`: Force the compositor to redraw a tab's BrowserView when the window shows a stale page; returns repaint_count so the repaint is provable.
- `browse_downloads`: List a tab's downloads with on-disk paths. Downloads are async: poll this after clicking export/download instead of expecting the path in the click response. (read-only)
- `browse_errors`: Read the main-process error log: uncaught exceptions, crashes, failed navigations, RPC errors. Each entry includes recent calls as context. Returns the on-disk JSONL path. (read-only)
- `browse_quit`: Gracefully shut down the AI Browser (releases resources).

## FAQ

### Can a human interact with the browser while the agent is using it?

Yes, the browser is a visible Electron window that remains interactive, allowing a human to take over or assist at any time.

### Does the agent need to start the browser manually?

No, the MCP server will automatically spawn the Electron process if it detects nothing is listening on the required port.

### Is the browser headless?

No, it is a visible Electron application that renders a real window.

### How secure is the connection?

The WebSocket server binds to loopback only and rejects handshakes with an Origin header to prevent web pages from controlling the browser.
