内容
# 🖥️ MCP-RealBrowser
> **将 AI 连接到您的真实浏览器 — 而不是空白的测试窗口。**
>
> 您的登录信息、Cookie、扩展程序和会话均保持完整。
> Claude Code 看到的和您看到的一样，点击的也是您点击的。
[](LICENSE)
[](https://www.typescriptlang.org/)
[](https://modelcontextprotocol.io/)
[](https://github.com/obbbba/mcp-realbrowser/actions/workflows/ci.yml)
---
## 为什么存在
现有的所有 MCP 浏览器工具都会启动一个**全新的空白浏览器**：
| 工具 | 问题 |
|------|---------|
| `@playwright/mcp` | 新的隐身窗口 — 没有登录信息，没有 Cookie |
| `browser-use` | 仅限 Python，不支持 MCP |
| `stagehand` | 数据提取为重点，而不是一般浏览 |
**MCP-RealBrowser** 通过 CDP 连接到您**已经运行的** Chrome 浏览器。
您已经登录了 Twitter、Gmail、淘宝或公司 CRM？
AI 看到了所有这些。无需重新登录。无需验证码地狱。无需“请复制粘贴此内容”。
---
## 功能
```
您： "检查我的未读邮件并总结它们"
AI： navigate(gmail.com) → snapshot() → extract() → 读取并总结
您： "查找下周五东京的航班，价格不超过 ¥3000"
AI： navigate(ctrip.com) → fill("出发", "上海") → fill("到达", "东京")
→ click("搜索") → extract() → 有序结果
您： "打开我的 GitHub，告诉我我有多少颗星"
AI： navigate(github.com/obbbba) → snapshot() → "您有 1 颗星"
```
---
## 快速开始
### 1. 安装
```bash
git clone https://github.com/obbbba/mcp-realbrowser.git
cd mcp-realbrowser
npm install
npm run build
```
### 2. 运行诊断
```bash
node dist/index.js --doctor
```
检查：Node.js、依赖项、Chrome 已安装、Chrome 正在运行、CDP 端口已打开、调试标志已启用。
### 3. 以调试端口启动浏览器
> ⚠️ **关闭所有浏览器窗口** （包括系统托盘）。浏览器必须使用 `--remote-debugging-port=9222` 启动。
**Windows（Edge — 推荐，预装于 Win11）：**
```bat
scripts\launch-edge.bat
```
**Windows（Chrome）：**
```bat
scripts\launch-chrome.bat
```
**Mac/Linux：**
```bash
chmod +x scripts/launch-chrome.sh
./scripts/launch-chrome.sh
```
**或手动：**
```bash
# Mac
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222
# Windows
"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222
# Linux
google-chrome --remote-debugging-port=9222
```
### 4. 选择模式
#### 模式 A：MCP 服务器（推荐 — Claude Code 自动控制）
在您的项目中将以下内容添加到 `.claude/settings.json`：
```json
{
"mcpServers": {
"realbrowser": {
"command": "npx",
"args": ["tsx", "/path/to/mcp-realbrowser/src/index.ts"],
"env": { "CDP_PORT": "9222" }
}
}
}
```
重启 Claude Code。现在您可以直接对话：
```
> 去百度.com 并搜索"MCP 教程"
> 打开 GitHub 趋势页面并找到排名靠前的 TypeScript 仓库
> 导航到我的 Gmail 并总结未读邮件
```
#### 模式 B：直接 API（用于脚本/自定义工具）
```ts
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 看到的页面
await browser.click("Sign in");
await browser.type("hello");
const screenshot = await browser.screenshot();
await browser.disconnect(); // Chrome 保持打开
```
### 5. 验证其工作
```bash
npx tsx src/smoke-test.ts
# 期望：测试运行通过
```
---
## 工具（20）
| 工具 | 功能 |
|------|-------------|
| `navigate(url)` | 在当前标签页中打开任意 URL |
| `snapshot(query?)` | 获取交互式元素 — 使用 `query` 过滤以节省令牌 |
| `click(target)` | 通过 CSS 选择器、文本、角色、占位符或标签（6 种策略）点击 |
| `type(text)` | 在聚焦的输入框中输入内容，带有类似人类的延迟 |
| `press_key(key)` | 按 Enter、Tab、Escape、箭头键等 |
| `screenshot(format?, quality?)` | 截取视口截图（PNG/JPEG，JPEG 质量 10-100） |
| `extract(maxChars?)` | 获取可见文本（默认 3K 字符，最大 30K） |
| `scroll(direction, amount?)` | 滚动上下，返回滚动位置 |
| `fill(field, value)` | 通过占位符或标签填充输入框 |
| `select_option(target, value)` | 在 `<select>` 下拉菜单中选择选项 |
| `go_back()` | 在浏览器历史记录中后退 |
| `go_forward()` | 在浏览器历史记录中前进 |
| `reload()` | 重新加载当前页面 |
| `hover(target)` | 悬停在元素上（下拉菜单、工具提示） |
| `wait_for_text(text, timeout?)` | 等待文本出现 |
| `list_tabs()` | 列出所有打开的浏览器标签页，包含索引、URL 和标题 |
| `select_tab(index)` | 通过索引切换到标签页 |
| `new_tab(url?)` | 打开新的浏览器标签页 |
| `close_tab(index)` | 通过索引关闭标签页 |
| `reconnect()` | 在浏览器重启后重新连接 |
### 💡 节省令牌的提示
```
snapshot(query="login") — 仅匹配"login"的元素
extract(maxChars=500) — 小片段，而不是完整页面
screenshot(format="jpeg", quality=40) — 紧凑的视觉检查
```
---
## 架构
```
┌──────────────┐ stdio (MCP) ┌──────────────────┐ CDP (ws) ┌──────────────┐
│ Claude Code │ ◄────────────────► │ MCP-RealBrowser │ ◄──────────────► │ 您的 Chrome │
│ （AI 代理） │ JSON-RPC 2.0 │ （TypeScript） │ DevTools Proto │ （真实数据） │
└──────────────┘ └──────────────────┘ └──────────────┘
│
│ chromium.connectOverCDP()
│ DOM 快照（交互式元素）
│ page.screenshot()
│ page.keyboard.type()
▼
┌──────────────┐
│ Playwright │
└──────────────┘
```
关键设计决策：
- **CDP 而不是启动**：连接到**您的**浏览器，而不是全新的浏览器
- **用于视觉的 DOM 快照**：结构化、快速，250 个元素的限制以保持上下文可控
- **截图作为后备**：用于视觉页面，其中 DOM 结构不够用
- **断开连接 ≠ 关闭**：关闭 MCP 服务器不会关闭您的浏览器
- **--doctor 模式**：在启动服务器之前诊断 Chrome/CDP 问题
---
## 故障排除
### "CDP 端口不接受连接"（最常见）
这意味着 Chrome 正在运行，但**没有**带有 `--remote-debugging-port` 标志。
**修复：**
```bash
# 1. 杀死所有 Chrome 进程（是的，所有进程 — 包括系统托盘）
# Windows：
taskkill /F /IM chrome.exe
# Mac：
pkill -f "Google Chrome"
# 2. 重新启动调试标志
scripts/launch-chrome.bat # Windows
./scripts/launch-chrome.sh # Mac/Linux
# 3. 验证端口是否打开
curl http://localhost:9222/json/version
```
### "我的 Chrome 使用哪个端口？"
运行 `--doctor` 诊断所有常见问题：
```bash
node dist/index.js --doctor
# 新增：自动修复 — 杀死卡死的浏览器并使用调试标志启动
node dist/index.js --doctor --fix
```
### 空白页面 / 无内容
某些网站阻止自动化。尝试：
1. 使用 `screenshot` 代替 `snapshot` 用于视觉页面
2. 使用 `extract` 用于文本丰富的页面
3. 部分 SPA 需要 `wait_for_text` 在导航后
### Chrome 启动但忽略标志
Chrome 可能会拾取现有的会话。使用单独的配置文件：
```bash
chrome --remote-debugging-port=9222 --user-data-dir="%TEMP%\chrome-mcp-profile"
```
---
## 支持的浏览器
| 浏览器 | 支持 | 备注 |
|---------|---------|-------|
| Edge | ✅ 完整 | 预装于 Win11，相同的 CDP |
| Chrome | ✅ 完整 | 所有平台 |
| Brave | ✅ 完整 | 基于 Chromium |
| Arc | ✅ 完整 | 基于 Chromium |
| Opera | ✅ 完整 | 基于 Chromium |
| 360 / QQ / Sogou | ⚠️ 可能 | 基于 Chromium，未测试 |
| Firefox | 🔜 第二阶段 | 通过 WebDriver BiDi |
| Safari | 🔜 第三阶段 | 仅限 macOS |
---
## 贡献
欢迎拉取请求！您可以帮助的领域：
- **新工具** — 需要 `drag_and_drop` 或 `select_option`？直接提交 PR。
- **错误修复** — 发现了边缘情况？修复它。
- **文档** — 更好的示例、翻译、教程。
- **测试** — 更多针对边缘情况的覆盖。
1. 分叉它
2. 创建您的功能分支 (`git checkout -b feature/amazing`)
3. 运行烟雾测试：`npx tsx src/smoke-test.ts` — 应该为 13/13
4. 提交 (`git commit -m '添加一些很酷的东西'`)
5. 推送 + 打开拉取请求
---
## 许可证
MIT © 2024
---
## 星级历史
如果这很有用，GitHub 上的 ⭐️ 对您来说意义重大 — 它告诉其他人该项目值得他们花费时间。
---
[中文说明](#中文)
### 中文说明
**MCP-RealBrowser** 是一个 MCP 服务器，让 AI 助手（Claude Code、Cursor 等）连接您**真实的 Chrome 浏览器**进行操作，保留所有登录态、Cookie、插件。
**与现有方案的区别：** Playwright MCP / Browser-Use / Stagehand 都会启动全新的空白浏览器——没有登录状态。MCP-RealBrowser 通过 CDP 协议直连您正在使用的 Chrome。
**两种使用方式：**
**A. MCP Server 模式（推荐）：**
1. `git clone https://github.com/obbbba/mcp-realbrowser.git` → `npm install` → `npm run build`
2. `node dist/index.js --doctor` 诊断环境
3. 关闭所有 Chrome 窗口，运行 `scripts/launch-chrome.bat`
4. 在 `.claude/settings.json` 中配置 MCP Server（见上方 JSON）
5. 重启 Claude Code，直接说"帮我打开百度搜索 MCP 教程"
**B. 直接 API 模式：**
```ts
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` → 🎉 13/13 通过
**14 个工具：** navigate / snapshot / click / type / press_key / screenshot / extract / scroll / fill / go_back / go_forward / reload / hover / wait_for_text
**故障排除：** 运行 `--doctor` 诊断。最常见的问题：Chrome 启动时没带 `--remote-debugging-port=9222` 参数。
