MCP-RealBrowser

MCP-RealBrowser

Provides a persistent browser profile for AI agents, enabling them to log in once and maintain sessions across restarts. Supports 20 tools for browsing, navigation, text extraction, and screenshot.

Category
访问服务器

README

🖥️ 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.

License: MIT TypeScript MCP CI

Why this exists

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

Tool Problem
@playwright/mcp New incognito window, temporary profile — lost on restart
browser-use Python-only, doesn't speak MCP
stagehand Data extraction focus, not general browsing

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.

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)

Tool What it does
navigate(url) Open any URL in the current tab
snapshot(query?) Get interactive elements — filter with query to save tokens
click(target) Click by CSS selector, text, role, placeholder, or label (6 strategies)
type(text) Type into the focused input with human-like delay
press_key(key) Press Enter, Tab, Escape, arrows, etc.
screenshot(format?, quality?) Take a viewport screenshot (PNG/JPEG, quality 10-100 for JPEG)
extract(maxChars?) Get visible text (default 3K chars, max 30K)
scroll(direction, amount?) Scroll up/down, returns scroll position
fill(field, value) Fill an input by placeholder or label
select_option(target, value) Select an option in a <select> dropdown
go_back() Navigate back in browser history
go_forward() Navigate forward in browser history
reload() Reload the current page
hover(target) Hover over an element (dropdowns, tooltips)
wait_for_text(text, timeout?) Wait for text to appear after an action
list_tabs() List all open browser tabs with index, URL, and title
select_tab(index) Switch to a tab by index
new_tab(url?) Open a new browser tab
close_tab(index) Close a tab by index
reconnect() Reconnect to browser after restart

💡 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

Browser Support Notes
Edge ✅ Full Pre-installed on Win11, same CDP
Chrome ✅ Full All platforms
Brave ✅ Full Chromium-based
Arc ✅ Full Chromium-based
Opera ✅ Full Chromium-based
360 / QQ / Sogou ⚠️ Likely Chromium-based, not tested

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，自动读取系统默认浏览器。

推荐服务器

Baidu Map

Baidu Map

百度地图核心API现已全面兼容MCP协议，是国内首家兼容MCP协议的地图服务商。

官方
精选
JavaScript
Playwright MCP Server

Playwright MCP Server

一个模型上下文协议服务器，它使大型语言模型能够通过结构化的可访问性快照与网页进行交互，而无需视觉模型或屏幕截图。

官方
精选
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

一个由人工智能驱动的工具，可以从自然语言描述生成现代化的用户界面组件，并与流行的集成开发环境（IDE）集成，从而简化用户界面开发流程。

官方
精选
本地
TypeScript
Audiense Insights MCP Server

Audiense Insights MCP Server

通过模型上下文协议启用与 Audiense Insights 账户的交互，从而促进营销洞察和受众数据的提取和分析，包括人口统计信息、行为和影响者互动。

官方
精选
本地
TypeScript
VeyraX

VeyraX

一个单一的 MCP 工具，连接你所有喜爱的工具：Gmail、日历以及其他 40 多个工具。

官方
精选
本地
graphlit-mcp-server

graphlit-mcp-server

模型上下文协议 (MCP) 服务器实现了 MCP 客户端与 Graphlit 服务之间的集成。 除了网络爬取之外，还可以将任何内容（从 Slack 到 Gmail 再到播客订阅源）导入到 Graphlit 项目中，然后从 MCP 客户端检索相关内容。

官方
精选
TypeScript
Kagi MCP Server

Kagi MCP Server

一个 MCP 服务器，集成了 Kagi 搜索功能和 Claude AI，使 Claude 能够在回答需要最新信息的问题时执行实时网络搜索。

官方
精选
Python
e2b-mcp-server

e2b-mcp-server

使用 MCP 通过 e2b 运行代码。

官方
精选
Neon MCP Server

Neon MCP Server

用于与 Neon 管理 API 和数据库交互的 MCP 服务器

官方
精选
Exa MCP Server

Exa MCP Server

模型上下文协议（MCP）服务器允许像 Claude 这样的 AI 助手使用 Exa AI 搜索 API 进行网络搜索。这种设置允许 AI 模型以安全和受控的方式获取实时的网络信息。

官方
精选