Home-Browser MCP

Browse the web through your home residential IP — bypass datacenter bans, Cloudflare Turnstile, and anti-bot walls for Muse, Groq bots, cloud agents, and AI assistants.

---

⚡ One-Click Quickstart (Home Computer)

On the machine at home you want to browse through:

🍏 macOS / 🐧 Linux / 🥧 Raspberry Pi:

# (On a bare minimal Linux/Proxmox server without git, run: apt update && apt install -y git)
git clone https://github.com/onlinegill/home-browser-mcp.git
cd home-browser-mcp
./setup.sh

🪟 Windows (Command Prompt or PowerShell):

git clone https://github.com/onlinegill/home-browser-mcp.git
cd home-browser-mcp
setup.bat

(Or in PowerShell: .\setup.ps1)

The setup script does everything automatically:

1. ✅ Detects OS & Prereqs: Verifies environment across macOS, Linux (Debian, Ubuntu, Proxmox, Arch), and Windows, auto-installing Git if missing.
2. ✅ Auto-installs System Packages: Automatically detects and installs missing python3-venv / pip on Debian/Ubuntu/Proxmox systems.
3. ✅ Tailscale Network Check: Checks for Tailscale; if missing, optionally offers one-click install so remote bots can connect without router port-forwarding.
4. ✅ Virtual Environment & Dependencies: Initializes isolated .venv and installs MCP + Scrapling stealth engines (patchright, curl-cffi, mcp).
5. ✅ Stealth Browser Binaries: Downloads required stealth browser drivers (scrapling install).
6. ✅ Global CLI Shortcut: Symlinks hbm to your PATH (/usr/local/bin/hbm or ~/.local/bin/hbm).
7. ✅ Instant Integration Configs: Automatically outputs personalized, copy-pasteable JSON configs and prompts for Muse, Groq, Claude Desktop, and Cursor.

Test it immediately on your home machine:

./hbm fetch https://example.com

---

The Problem

Anti-bot systems (Cloudflare, Akamai, PerimeterX, Datadome, AWS WAF) use a two-layer defense:

Layer 1: IP / ASN Reputation      ──▶  Instantly flags Datacenter ASNs (AWS, GCP, VPS, Groq/Muse cloud)
Layer 2: Browser Fingerprinting   ──▶  Instantly flags automation leaks (CDP artifacts, navigator.webdriver)

1. Cloud & VPS IPs are blacklisted by default: When your Muse or Groq bot fetches an Amazon, retail, or news page from a cloud server, it gets an immediate 403 Forbidden or Cloudflare challenge because of the datacenter ASN.
2. Standard headless browsers leak fingerprints: Even if you route traffic, vanilla headless browsers fail modern JavaScript challenges and Cloudflare Turnstile due to exposed automation flags.

---

The Solution

Home-Browser MCP pairs a clean residential ISP connection with two specialized MCP browser engines:

┌─────────────────────────────────────────┐
│  AI Bot or Assistant                    │
│  • Muse bots & Groq agents              │
│  • Claude Code, Cursor, Claude Desktop  │
│  • LangChain / custom cloud agents      │