🖥️ MCP-RealBrowser

A persistent browser profile for your AI — log in once, sessions stay forever.

No more blank browser windows. No more "please copy-paste this page." Give your AI a dedicated browser identity, and it remembers everything.

Why this exists

Every existing MCP browser tool launches a fresh, blank browser that forgets everything when closed:

MCP-RealBrowser gives your AI a persistent browser profile — same directory, same cookies, same sessions across restarts. Log into GitHub, Gmail, Bilibili once, and it stays logged in forever.

Related MCP server: Navvi

What it does

You: "Check my unread emails and summarize them"
AI:  navigate(gmail.com) → snapshot() → extract() → reads & summarizes

You: "Find flights to Tokyo next Friday under ¥3000"
AI:  navigate(ctrip.com) → fill("出发", "上海") → fill("到达", "东京")
     → click("搜索") → extract() → sorted results

You: "Open my GitHub and tell me how many stars I have"
AI:  navigate(github.com/obbbba) → snapshot() → "You have 1 star"

Quick start

1. Install

git clone https://github.com/obbbba/mcp-realbrowser.git
cd mcp-realbrowser
npm install
npm run build

2. Run diagnostics

node dist/index.js --doctor

Checks: Node.js, dependencies, Chrome installed, Chrome running, CDP port open, debug flag enabled.

3. Launch your browser with debug port

The browser uses a separate persistent profile — your daily browser isn't affected.

Windows (Edge — pre-installed on Win11):

scripts\launch-edge.bat

Windows (Chrome):

scripts\launch-chrome.bat

Mac/Linux:

chmod +x scripts/launch-chrome.sh
./scripts/launch-chrome.sh

4. Choose your mode

Mode A: MCP Server (recommended — Claude Code auto-control)

Add to .claude/settings.json in your project:

{
  "mcpServers": {
    "realbrowser": {
      "command": "npx",
      "args": ["tsx", "/path/to/mcp-realbrowser/src/index.ts"],
      "env": { "CDP_PORT": "9222" }
    }
  }
}

Restart Claude Code. Now you can just talk:

> Go to baidu.com and search for "MCP tutorial"
> Open GitHub trending page and find the top TypeScript repo
> Navigate to my Gmail and summarize unread emails

Mode B: Direct API (for scripts / custom tools)

import { CDPConnection } from "mcp-realbrowser";

const browser = new CDPConnection();
await browser.connect("http://localhost:9222");

await browser.navigate("github.com");
const snapshot = await browser.snapshot(); // AI sees the page
await browser.click("Sign in");
await browser.type("hello");
const screenshot = await browser.screenshot();

await browser.disconnect(); // Chrome stays open

5. Verify it works

npx tsx src/smoke-test.ts
# Expected: test runs pass

Tools (20)

💡 Token-saving tips

snapshot(query="login")    — only elements matching "login"
extract(maxChars=500)      — small snippets, not full pages
screenshot(format="jpeg", quality=40) — compact visual check

Architecture

┌──────────────┐     stdio (MCP)     ┌──────────────────┐     CDP (ws)     ┌──────────────────┐
│  Claude Code │ ◄────────────────► │  MCP-RealBrowser  │ ◄──────────────► │  Browser profile │
│  (AI Agent)  │   JSON-RPC 2.0     │  (TypeScript)     │   DevTools Proto │  (persistent)    │
└──────────────┘                    └──────────────────┘                  └──────────────────┘
                                           │
                                           │  chromium.connectOverCDP()
                                           │  DOM snapshot (interactive elements)
                                           │  page.screenshot()
                                           │  page.keyboard.type()
                                           ▼
                                    ┌──────────────┐
                                    │   Playwright  │
                                    └──────────────┘

Key design decisions:

• Persistent profile: Browser data saved to %LOCALAPPDATA%\mcp-realbrowser\ — cookies, logins, localStorage survive browser restarts

• CDP attach (not launch): Uses connectOverCDP — the browser process lives independently from the MCP server

• DOM snapshot for vision: Structured element scan, 250-element limit keeps context manageable

• Screenshot as fallback: For visual pages where DOM structure isn't enough

• Disconnect ≠ Close: Shutting down the MCP server never closes your browser

• --doctor mode: Diagnose and auto-fix browser/CDP issues before starting the server

Troubleshooting

"CDP port not accepting connections"

The browser isn't running with the debugging flag.

Quick fix:

# One command to diagnose and auto-fix
node dist/index.js --doctor --fix

Or manually:

# 1. Kill stale browser processes
taskkill /F /IM msedge.exe & taskkill /F /IM chrome.exe

# 2. Run the launch script
scripts\launch-edge.bat   # Windows (Edge)
scripts\launch-chrome.bat # Windows (Chrome)
./scripts/launch-chrome.sh # Mac/Linux

Other issues

Run --doctor for a full diagnostic report:

node dist/index.js --doctor

First time? Log in to your sites

The profile is empty on first launch. Log into GitHub, Gmail, Bilibili, etc. once — cookies are saved to %LOCALAPPDATA%\mcp-realbrowser\browser-profile and persist forever.

Supported browsers

Contributing

Pull requests welcome! Areas you can help:

• New tools — want drag_and_drop or select_option? PR it.

• Bug fixes — found an edge case? Fix it.

• Docs — better examples, translations, tutorials.

• Tests — more coverage for edge cases.

1. Fork it

2. Create your feature branch (git checkout -b feature/amazing)

3. Run the smoke test: npx tsx src/smoke-test.ts — should be 13/13

4. Commit (git commit -m 'Add something amazing')

5. Push + open a Pull Request

License

MIT © 2024

Star History

If this is useful, a ⭐ on GitHub makes a big difference — it tells others the project is worth their time.

中文说明

中文说明

MCP-RealBrowser 是一个 MCP 服务器，为 AI 助手提供持久化的浏览器身份。独立 profile 不影响你的日常浏览器。登录一次 GitHub、B 站、Gmail——Cookies 永久保存到 %LOCALAPPDATA%\mcp-realbrowser\browser-profile，关了再开登录态还在。

与现有方案的区别： Playwright MCP 每次启动临时 profile，关闭即销毁。我们用固定持久目录，登录态跨会话保留。

两种使用方式：

A. MCP Server 模式（推荐）：

1. git clone → npm install → npm run build

2. node dist/index.js --doctor --fix 一键诊断并启动浏览器

3. 在 .claude/settings.json 中配置 MCP Server

4. 重启 Claude Code，直接说话

B. 直接 API 模式：

import { CDPConnection } from "mcp-realbrowser";
const browser = new CDPConnection();
await browser.connect("http://localhost:9222");
await browser.navigate("github.com");
await browser.click("Sign in");
await browser.disconnect();

验证： npx tsx src/smoke-test.ts

20 个工具： navigate / snapshot / click / type / press_key / screenshot / extract / scroll / fill / select_option / go_back / go_forward / reload / hover / wait_for_text / list_tabs / select_tab / new_tab / close_tab / reconnect

故障排除： --doctor --fix 自动检测并修复。支持 Edge / Chrome / Brave / Arc / Opera / Vivaldi / Chromium，自动读取系统默认浏览器。