browser-use-ai 0.1.0
Headed/headless PyQt5/QWebEngine browser exposed as an MCP stdio server.
Requires Python: >=3.10
Keywords: mcp, browser, pyqt5, ai-agent, automation

# browser_use

`browser_use` is a local `PyQt5 + QWebEngine` browser exposed through MCP (stdio), designed for autonomous agents.

It includes:
- real Chromium rendering,
- headed or headless operation,
- multi-tab control,
- download interception with accept/reject,
- persistent SQLite history/download metadata,
- dual KV stores:
  - in-memory KV (process lifetime),
  - persistent KV (JSON on disk).

## Features

- Navigation + tab control
- DOM inspection + interaction (click/type/wait/eval)
- Download management
- Persistent history
- In-memory and persistent KV memory
- Screenshots + full snapshot payloads

## Install

1. Install Qt bindings:

```bash
brew install pyqt@5
```

2. Create a venv in this folder (`/Users/moon/Documents/ai_browser_mcp`):

```bash
python3 -m venv .venv
source .venv/bin/activate
```

3. Install dependencies:

```bash
python3 -m pip install -r requirements.txt
```

4. Optional editable install:

```bash
python3 -m pip install -e .
```

CLI entrypoint:

```bash
browser_use
```

## Run

Headed:

```bash
python3 server.py --mode headed --url "https://example.com"
```

Headless:

```bash
python3 server.py --mode headless --url "https://example.com"
```

Boot check:

```bash
python3 server.py --headless --boot-check-seconds 4
```

## Storage Defaults

If not overridden, storage is package-local (`browser_use/`):

- screenshots: `browser_use/screenshots/`
- browser profile: `browser_use/profile/`
- SQLite DB: `browser_use/data/browser.sqlite3`
- downloads: `browser_use/data/downloads/`
- persistent KV JSON: `browser_use/data/kv_store.json`

Override if needed:

```bash
python3 server.py \
  --mode headed \
  --downloads-dir "/tmp/browser-use-downloads" \
  --db-path "/tmp/browser-use.sqlite3" \
  --kv-path "/tmp/browser-use-kv.json"
```

## MCP Config Example

```json
{
  "mcpServers": {
    "browser_use": {
      "command": "python3",
      "args": [
        "/Users/moon/Documents/ai_browser_mcp/server.py",
        "--mode",
        "headed"
      ]
    }
  }
}
```

## Tool Groups

Navigation:
- `browser_state`
- `browser_navigate`
- `browser_wait_for_url`
- `browser_go_back`
- `browser_go_forward`
- `browser_reload`
- `browser_get_navigation_history`

Tabs:
- `browser_tabs_list`
- `browser_tab_new`
- `browser_tab_switch`
- `browser_tab_close`

DOM / interaction:
- `browser_get_dom`
- `browser_describe_dom_tree`
- `browser_query_selector_all`
- `browser_list_interactive_elements`
- `browser_click`
- `browser_type_text`
- `browser_wait_for_selector`
- `browser_eval_js`

Downloads:
- `browser_get_downloads`
- `browser_decide_download`
- `browser_cancel_download`

Persistence:
- `browser_get_persistent_history`
- `browser_clear_persistent_history`

Persistent KV:
- `browser_persist_kv_set`
- `browser_persist_kv_get`
- `browser_persist_kv_list`
- `browser_persist_kv_query`
- `browser_persist_kv_delete`
- `browser_persist_kv_clear`

In-memory KV:
- `browser_mem_kv_set`
- `browser_mem_kv_get`
- `browser_mem_kv_list`
- `browser_mem_kv_query`
- `browser_mem_kv_delete`
- `browser_mem_kv_clear`

Legacy aliases:
- `browser_kv_*` maps to persistent KV for backward compatibility.

Observability:
- `browser_get_console_logs`
- `browser_clear_console_logs`
- `browser_capture_screenshot`
- `browser_set_window_visibility`
- `browser_snapshot`

## KV Scope Guidance

- Use `browser_mem_kv_*` for temporary, per-run scratch values.
- Use `browser_persist_kv_*` for important durable values (tokens, passwords, long-lived notes).

## Notes

- Some sites require manual handoff for CAPTCHA/OTP/2FA.
- In headed mode, screenshots prefer real window capture (`capture_source: "window"`).
- Sensitive typed fields are redacted in action history.