# browser-agent

**An MCP server that gives Claude a real, persistent, logged-in Chrome browser.**

Most browser MCPs use headless Playwright. They get blocked by Cloudflare, lose sessions between conversations, and fail on sites that detect automation. `browser-agent` runs actual headful Google Chrome with persistent profiles — so Claude can log into sites once and use them forever, across every conversation.

---

## Why this exists

Headless browsers are fingerprinted and blocked. Real Chrome isn't.

When you need Claude to operate on LinkedIn, Gmail, Google Search Console, Discord, WhatsApp Web, YouTube Studio, or any site that requires a real logged-in session — headless fails. `browser-agent` solves this by giving Claude a real Chrome instance with:

- Your actual cookies and login state (persistent across restarts and conversations)
- A residential proxy so it looks like a real user from a real ISP
- A cross-session knowledge base so Claude learns how each site works and never rediscovers the same traps
- A recipe system so proven multi-step flows can be saved and replayed

---

## Features

### 50+ MCP tools across 8 categories

**Navigation & Interaction**
- `browser_navigate` — go to a URL, wait for load
- `browser_snapshot` — compact role+name outline with clickable refs (preferred over screenshots)
- `browser_click`, `browser_click_text`, `browser_click_xy` — click by ref, text, or coordinates
- `browser_type`, `browser_fill` — type into inputs
- `browser_scroll`, `browser_press`, `browser_back` — keyboard and scroll
- `browser_do` — batch an entire flow into one tool call (saves 10x round-trips)

**Reading & Scraping**
- `browser_read_text` — extract readable text from a page or selector
- `browser_elements` — full element tree with refs
- `browser_eval` — run arbitrary JavaScript
- `browser_console` — read browser console logs
- `browser_aria` — native accessibility tree

**Network & Downloads**
- `browser_fetch` — fetch a URL in the browser's authenticated session (bypasses CORS)
- `browser_request` — make raw HTTP requests with the browser's cookies
- `browser_download` — download a file
- `browser_list_downloads` — list downloaded files
- `browser_network` — inspect network requests

**Profile Management**
- `browser_profile` — switch to a named profile (each has its own Chrome, cookies, proxy)
- `browser_profiles` — list all registered profiles
- `browser_add_profile` — create a new profile with optional custom proxy
- `browser_free_profiles` — stop idle profile browsers to reclaim RAM
- `browser_export_session`, `browser_import_session` — backup/restore login sessions

**Anti-Detection**
- `browser_solve_cloudflare` — handle Cloudflare challenges
- `browser_solve_captcha` — solve captchas via 2captcha API
- Stealth JS injected on every page (disables `navigator.webdriver`, spoofs fingerprints)
- WebRTC forced through proxy (no IP leak)
- `--disable-blink-features=AutomationControlled` + real Chrome flags

**Knowledge & Recipes**
- `browser_knowledge` — recall what Claude has learned about a site (shared across sessions)
- `browser_learn` — save a tip, recipe, or gotcha for a domain
- `browser_save_recipe` — save a proven multi-step flow
- `browser_run_recipe` — replay a saved recipe
- `browser_list_recipes` — see all saved recipes
- `browser_maintenance` — review the knowledge backlog

**Live View**
- `browser_login_view` — open noVNC so you can manually log into a site by hand
- `browser_login_done` — confirm login complete, returns page state
- `browser_view` / `browser_view_stop` — watch the browser live in your browser
- `browser_screenshot` — capture a screenshot

**Session Control**
- `browser_status` — current profile, proxy, idle state, page title
- `browser_restart` — restart Chrome (keeps profile)
- `browser_stop` — shut down Chrome and VNC
- `browser_pages`, `browser_switch_page` — manage multiple open tabs
- `browser_close_own_tabs` — close tabs opened this session
- `browser_idle_autoclose` — toggle auto-close after inactivity
- `browser_wait` — wait N milliseconds

---

## Architecture

```
Claude Code (stdio MCP)
    │
    ▼
server.py  ─── FastMCP (Python 3.11)
    │
    ├── browser.py      Chrome CDP session management
    ├── profiles.py     Multi-profile registry + port allocation
    ├── proxy.py        Residential proxy + local SOCKS5 relay
    ├── config.py       Per-profile configuration
    ├── stealth.js      Anti-fingerprint JS injected on every page
    ├── knowledge/      Cross-session site knowledge (JSON per domain)
    └── recipes/        Saved replayable flows (JSON)
    │
    ▼
Real headful Chrome (Xvfb display)
    │
    ├── Per-profile user data dir  (logins survive restarts)
    ├── Residential proxy          (real ISP egress IP)
    └── noVNC live view            (watch/control via browser)
```

Each profile gets its own:
- Chrome user data directory (isolated cookies, localStorage, extensions)
- Xvfb display number
- CDP port
- VNC port
- Proxy (can override global proxy per profile)

---

## Built-in knowledge base

The repo ships with cross-session knowledge for 25+ domains accumulated from real production use:

`gmail` · `google search` · `google drive` · `youtube` · `youtube studio` · `linkedin` · `discord` · `whatsapp web` · `upwork` · `fiverr` · `freelancer` · `metricool` · `chatgpt` · `gemini` · `google labs` · `hostinger panel` · `spaceship` · `flowcv` · `sendpulse` and more.

Each entry contains proven recipes, known gotchas, and site-specific tips — so Claude doesn't rediscover the same traps in future conversations.

---

## Setup

### Requirements

- Linux (tested on AlmaLinux 9 / Ubuntu 22+)
- Python 3.11+
- Google Chrome (`/usr/bin/google-chrome`)
- Xvfb (`xorg-x11-server-Xvfb`)
- x11vnc + websockify (for live view)
- A residential SOCKS5 proxy (required for production use; SSH tunnel supported for dev)

### Install

```bash
git clone https://github.com/ahsaanfarooq/browser-agent
cd browser-agent
python3.11 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

### Configure

```bash
cp proxy.env.example proxy.env
# Edit proxy.env: set PROXY_SOURCE and proxy credentials
```

Key settings in `config.py`:

| Variable | Default | Description |
|---|---|---|
| `DISPLAY` | `:1` | Xvfb display number |
| `CDP_PORT` | `9222` | Chrome DevTools Protocol port |
| `HOST_IP` | — | Your server IP (for live view URLs) |
| `SCREEN` | `1920x1080x24` | Virtual display resolution |

### Add to Claude Code

```json
{
  "mcpServers": {
    "browser-agent": {
      "command": "/path/to/browser-agent/venv/bin/python",
      "args": ["/path/to/browser-agent/server.py"]
    }
  }
}
```

### Log in once, use forever

```
# Ask Claude:
"Open the browser view and navigate to gmail.com so I can log in"

# Claude calls browser_login_view("https://gmail.com")
# You see a live noVNC view, log in manually
# Claude calls browser_login_done() — session is now persisted
```

After logging in once, Claude can use that account in every future conversation without re-authenticating.

---

## How Claude uses it

**Token-lean** — `browser_snapshot` returns a compact text outline with inline refs. Claude reads once and acts — no repeated round-trips, no expensive screenshots for navigation.

**Batch flows** — `browser_do([...steps])` sends a whole sequence in one tool call with `wait_for` conditions. A 10-step flow = 1 API call.

**Gets smarter over time** — after solving a tricky interaction, Claude calls `browser_learn()` to save it for all future sessions. `browser_knowledge("site.com")` is auto-called on first visit each session, so Claude inherits everything learned before.

---

## Example use cases

- **Content operations** — manage 30+ WordPress sites, GSC, social accounts; check rankings, schedule posts, handle outreach
- **Freelance automation** — drive Upwork, Fiverr, LinkedIn with real sessions (no API required, no rate-limit blocks)
- **Research** — read Gmail threads, Google Docs, Discord servers, WhatsApp Web, paywalled pages
- **Monitoring** — check dashboards, analytics, server panels that have no API
- **Data extraction** — scrape sites protected by Cloudflare, login walls, or bot detection
- **Workflow automation** — fill forms, upload files, click through multi-step flows on any site

---

## Security notes

- Proxy is **fail-closed**: if the proxy is down, Chrome refuses to launch. Your real IP is never used.
- WebRTC is forced through the proxy (prevents IP leaks via `browser_eval`).
- VNC ports bind `127.0.0.1` only. Live view is accessed via SSH tunnel or an authenticated dashboard.
- Chrome runs with `--no-sandbox` (required on Linux servers without user namespaces). Run on a dedicated VPS, not your personal machine.

---

## License

MIT

---

## Author

**Ahsaan Farooq** — [ahsaanfarooq.tech](https://ahsaanfarooq.tech)

Built for real production automation across 30+ sites. Running daily since early 2026. Contributions welcome.