io.github.Shreyas-Profile/browser-mcp

browser-mcp

Built by **Shreyas** · Shipped by **Globalion**

Hosted Chrome as an MCP skill. Give any MCP-compatible agent (Claude Desktop, Cursor, custom scripts) a real Chromium browser to drive — navigate, click, type, snapshot, read pages, take screenshots. Human-like behaviour, per-user isolated sessions, encrypted credential storage so login-gated sites work without leaking passwords to the LLM.

• Real Chromium on our server via Playwright. Not headless-only tricks — full browser context.
• Stealth defaults — patches the most common bot-detection tells (navigator.webdriver, plugins, chrome runtime). Not bulletproof against heavy defences like Cloudflare Turnstile; v0.2 adds proxies + CAPTCHA solving.
• Per-user isolation — separate BrowserContext per user, so cookies + localStorage don't leak between accounts.
• Encrypted credentials — AES-256-GCM at rest. use_credentials types the password into the page server-side; the LLM never sees it.
• No LLM in our stack — your agent is the brain. We just drive the browser.

Hosted at browser.regiq.in.

Use it

1. Visit https://browser.regiq.in and sign in with Google or GitHub.
2. Generate an MCP API key on the dashboard.
3. Add to Claude Desktop's claude_desktop_config.json:

     {
       "mcpServers": {
         "browser": {
           "url": "https://browser.regiq.in/api/mcp",
           "headers": {
             "Authorization": "Bearer YOUR_KEY_HERE"
           }
         }
       }
     }

4. Restart Claude Desktop. Ask it: "open workit.info and search for placements in Cambridge." Your agent will call the browser tools and drive the page.

Tools

Handling login-gated sites

Your agent sees a login form. Flow:

1. Check for saved creds — list_saved_credentials().
2. If saved for this domain — call use_credentials(sessionId, "workit.info", "input[name=email]", "input[type=password]"). Server decrypts + types. Then click the submit button.
3. If not saved — tell the user: "I need your workit.info login to continue. Save it at https://browser.regiq.in/dashboard, then ask me again."

For MVP the user has to save creds via the dashboard. v0.2 will let the agent request creds through a paired channel (e.g. via telegram-mcp).

Self-host

You'll need:

• Docker + Compose
• A Google or GitHub OAuth client
• A public HTTPS domain (Cloudflare Tunnel or ngrok http 3013)
• ~4 GB RAM (Playwright + Chromium)

git clone https://github.com/globalion/browser-mcp
cd browser-mcp
cp .env.example .env
# fill NEXTAUTH_SECRET, GOOGLE_/GITHUB_*, PUBLIC_BASE_URL,
# and generate CRED_ENCRYPTION_KEY with `openssl rand -hex 32`
docker compose up -d
# open http://localhost:3013

Architecture

Your MCP agent  →  /api/mcp (Bearer auth)  →  In-memory session Map  →  Playwright BrowserContext
                                                    ↕
                                                Postgres (audit + credentials, AES-256-GCM)

Sessions live in the container's memory. A restart kills all active sessions — users just call browser_new_session again. Contexts auto-close after 15 min idle to free RAM.

Bot avoidance — realistic expectations

The stealth init script strips navigator.webdriver, adds fake plugins, exposes window.chrome.runtime, and patches the notifications permission oddity. Combined with a real Chromium binary (not headless-only) and realistic viewport/UA/timezone, that gets past most public sites.

Sites with serious anti-bot (Cloudflare Turnstile, PerimeterX, DataDome) will still detect. To bypass those you need:

• Residential proxies (~$50/mo services like Bright Data)
• CAPTCHA solving (~$0.001/solve via 2captcha)
• More elaborate fingerprint spoofing

That's v0.2 territory. For now, use browser-mcp on sites that aren't actively hunting bots.

License

MIT.