ai-browser

A full-featured terminal browser that an AI can completely control — navigate, read pages, log in, sign up, handle 2FA, generate disposable emails, store credentials, download files, and replay whole processes — from any MCP-capable agent (opencode, Claude Desktop, etc.). Humans get an interactive terminal CLI too.

No UI needed: it renders pages to plain text with numbered LINKS and FORMS so an AI can act on [3] or 1.2 without a DOM. It works with plain HTML (fast, zero heavy deps) and can optionally upgrade to a real headless Chromium engine when Playwright is available.

Features

Browser core

• Persistent session: cookies and history saved to ~/.ai-browser/, logins survive restarts.

• Deterministic addressing: pages render to text with numbered LINKS and FORMS; the AI acts by index (3, 1.2) or by name/id/CSS.

• Multiple tabs, each with its own history, one shared session.

• Page cache (LRU) — back/forward/reload are instant.

• Retry-with-backoff and gzip on all requests for speed and reliability.

• Proxy support (http://, socks5://).

AI agent tools (55 via MCP)

• Navigation: navigate, read_page, back/forward/reload, history, tabs, wait, wait_for_text, find_text, screenshot (JS mode), save/download/fetch.

• Forms: fill, check, select, submit, click, extract, extract_json.

• Auth: auto_login, auto_signup (auto-detects email/name/password/confirm fields), analyze_page (detects login/signup/CAPTCHA/2FA).

• Credential vault: save_credentials, get_credentials, list/delete, auto_login_vault — passwords obfuscated on disk.

• Disposable email (mail.tm API): create inbox, list messages, read, extract verification codes — so signups that need an email address work.

• Macros: record a whole process once, replay anywhere, with conditional steps (if_contains, goto, stop).

• Detection: CAPTCHA and 2FA/OTP pages are flagged so the AI knows a human step is required.

JavaScript (optional)

enable_js() upgrades to Playwright + Chromium headless for JS-only sites:

• pip install playwright && playwright install chromium

• (On Termux/Android use termux-x11; on desktop it works out of the box.)

Related MCP server: Mantis

Try it offline (no internet needed)

python demo_server.py        # terminal 1: a tiny login-protected site on :8080
python cli.py http://127.0.0.1:8080/login   # terminal 2: human browser
# login: admin / secret   (or emma / secret)

Or let the AI do the whole flow through MCP: navigate → signup → fetch → login → vault → email → macro.

Download & Install

1. Download the code

git clone https://github.com/void-builder-1/ai-browser.git
cd ai-browser

Or download the ZIP from GitHub: Code → Download ZIP, then unzip:

unzip ai-browser-main.zip
cd ai-browser-main

2. Install dependencies

Requires Python 3.8+ and pip:

pip install -r requirements.txt

(On Termux/Android: pkg install python && pip install -r requirements.txt. If pip is blocked system-wide, use a virtualenv: python -m venv venv && source venv/bin/activate.)

3. Run

python cli.py            # human terminal browser
python cli.py https://example.com   # open a URL directly

To uninstall, just delete the folder:

rm -rf ai-browser

Optional: JavaScript engine

pip install playwright && playwright install chromium

(On Termux/Android use termux-x11; on desktop it works out of the box.)

Let the AI drive it

With opencode

Add to opencode.json (project or ~/.config/opencode/opencode.json):

{
  "mcp": {
    "aibrowser": {
      "type": "local",
      "command": ["python3", "/absolute/path/to/aibrowser/mcp_server.py"]
    }
  }
}

Restart opencode, then tell it: "use the aibrowser MCP server to sign up on example.com and do X".

With any other MCP client

Point the client at aibrowser/mcp_server.py (stdio transport). 55 tools are exposed — the full list comes from tools/list, but the main workflow tools:

The AI workflow pattern

1. navigate("https://target-site.com/signup")

2. analyze_page() → see the form structure and any 2FA/CAPTCHA

3. email_create() → get a disposable address for the signup

4. auto_signup(email, "Str0ng!pass", "Alice")

5. email_messages() + email_code(msg_id) → read the verification email

6. fill("1.1", code) + submit("1") → finish verification

7. save_credentials(site, email, pass) → store for next time

8. get_cookies() to confirm the session; cookies persist on disk

CLI commands

open, links, forms, click, fill, check, select, submit, login, signup, analyze, vault/vaultsave/vaultget/vaultdel/ vlogin, mail/mailmsgs/mailread/mailcode, fetch, find, waitfor, cache, save, download, grab, grabjson, record, stop, run, macros, back, fwd, reload, cookies, clearcookies, history, js, shot, proxy, status, raw, url, title, help, quit.

Tests

python test_engine.py    # 37 checks: nav, auth, vault, tabs, macros, cache...

Limitations

• No JavaScript unless you install Playwright (then enable_js()).

• CAPTCHAs are detected and flagged for the AI, not solved automatically.

• 2FA codes are read from the disposable inbox when the site emails them.

License

MIT