ai-browser
A terminal browser that an AI can fully control — navigate, read pages, log in,fill forms, submit, and manage cookies — from any MCP-capable agent(opencode, Claude Desktop, etc.). Humans get an interactive terminal CLI too.
Features
- Persistent session: cookies and history are saved to
~/.ai-browser/, sologins survive restarts. - Deterministic addressing: pages are rendered to plain text with numberedLINKS and FORMS, so an AI can act on
[3]or1.2without a DOM. - Full AI control via MCP (stdio): navigate, click, fill, submit, back/forward,cookies, history, wait. The MCP server is zero-dependency by design —it speaks newline-delimited JSON-RPC directly.
- Interactive human mode:
python cli.py.
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 let the AI do it (see below) with the demo site as the target.
Install
pip install -r requirements.txt
python cli.py # human terminal browser
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 log intoexample.com and do X".
With any other MCP client
Point the client at mcp_server.py (stdio transport). Tools exposed:
| tool | purpose |
|---|---|
navigate(url) |
open a URL, returns text snapshot |
read_page() |
readable text + numbered links + forms |
list_links / list_forms |
enumerate |
click(target) |
by index 3 or text/URL fragment |
fill(target, value) |
by form.field index 1.2 or name/id |
submit(form="1") |
logins, registrations, searches |
back / forward / reload / history |
navigation |
get_cookies / set_cookie / clear_cookies |
sessions |
get_url / get_title / wait |
state |
The AI workflow pattern
navigate("https://target-site.com/login")read_page()→ see the numbered form fieldsfill("1.1", "username"),fill("1.2", "password")submit("1")→read_page()againget_cookies()to confirm the session; cookies persist on disk
Limitations
- No JavaScript (it fetches raw HTML like lynx/w3m). Sites that require JS forlogin won't work; most classic login/registration forms do.
- No rendering of images/CSS — text only, by design.
License
MIT
