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

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

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

{
  "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

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

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
knowledge		knowledge
profiles		profiles
tests		tests
.gitignore		.gitignore
README.md		README.md
admin_cli.py		admin_cli.py
agent.py		agent.py
ba_helpers.js		ba_helpers.js
browser.py		browser.py
config.py		config.py
gsc.py		gsc.py
logging_setup.py		logging_setup.py
mcp_drive.py		mcp_drive.py
profiles.py		profiles.py
proxy.env.example		proxy.env.example
proxy.py		proxy.py
requirements.txt		requirements.txt
server.py		server.py
smoke.py		smoke.py
stealth.js		stealth.js
taskgen.py		taskgen.py

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

browser-agent

Why this exists

Features

50+ MCP tools across 8 categories

Architecture

Built-in knowledge base

Setup

Requirements

Install

Configure

Add to Claude Code

Log in once, use forever

How Claude uses it

Example use cases

Security notes

License

Author

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

browser-agent

Why this exists

Features

50+ MCP tools across 8 categories

Architecture

Built-in knowledge base

Setup

Requirements

Install

Configure

Add to Claude Code

Log in once, use forever

How Claude uses it

Example use cases

Security notes

License

Author

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages