内容
# browser-mcp
<p align="center">
<a href="https://github.com/sandraschi/browser-mcp"><img src="https://img.shields.io/github/stars/sandraschi/browser-mcp?style=flat-square" alt="Stars"></a>
<a href="https://github.com/sandraschi/browser-mcp/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="License"></a>
<a href="https://python.org"><img src="https://img.shields.io/badge/Python-3.13+-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python"></a>
<a href="https://github.com/PrefectHQ/fastmcp"><img src="https://img.shields.io/badge/FastMCP-3.2-7c5cfc?style=flat-square" alt="FastMCP"></a>
<a href="https://playwright.dev/"><img src="https://img.shields.io/badge/Playwright-powered-45ba4b?style=flat-square" alt="Playwright"></a>
<a href=""><img src="https://img.shields.io/badge/fleet-SOTA-6366f1?style=flat-square" alt="Fleet SOTA"></a>
<a href=""><img src="https://img.shields.io/badge/coverage-85%25-success?style=flat-square" alt="Coverage"></a>
</p>
**浏览器自动化 + 书签管理 — 通过 MCP.** 一个统一的 MCP 服务器，用于控制 Chrome、Firefox、Edge 和 Brave：浏览页面、点击元素、截图，并跨所有主流浏览器管理书签。附带一个 React 网页应用仪表盘。
---
## 功能
### 浏览器自动化（Playwright + CDP + CLI）
| 工具 | 描述 |
|------|-------------|
| `browse_page(url)` | 导航并提取可见文本 |
| `click_element(selector)` | 通过 CSS 选择器点击元素 |
| `extract_text(selector)` | 从任意元素提取文本 |
| `fill_input(selector, text)` | 在输入字段中输入文本 |
| `press_key(key)` | 按键盘键 |
| `screenshot()` | 视口 PNG 截图 |
| `browse_url_cli(url, browser)` | 无头 CLI 模式（无 Playwright 开销） |
| `list_browsers()` | 检测已安装的浏览器和配置文件 |
### 书签管理（4 种浏览器）
17 种操作，适用于 Chrome、Firefox、Edge 和 Brave：
- **CRUD**：列出、获取、添加、编辑、删除书签
- **搜索**：按标题/URL 进行全文搜索
- **跨浏览器同步**：在任意两个浏览器之间迁移书签
- **去重**：查找重复 URL（Firefox）
- **标签管理**：列出、查找相似、合并、清理标签（Firefox）
- **年龄分析**：查找旧或遗忘的书签，获取统计信息（Firefox）
- **链接检查**：检测损坏的链接（Firefox）
- **导出**：书签导出为 JSON/CSV（Firefox）
书签直接读写到浏览器的原生存储：
- **Firefox**：SQLite（`places.sqlite`），强制解锁以读取运行中的数据
- **Chrome/Edge/Brave**：Chromium `Bookmarks` JSON 文件
### 网页应用仪表盘（React + Vite）
一个完整的 React 单页应用，端口为 `10781`，具有：
- **仪表盘**：健康状态，已安装浏览器检测
- **书签面板**：按浏览器列出书签，实时搜索
---
## 快速开始
```powershell
git clone https://github.com/sandraschi/browser-mcp
cd browser-mcp
just
```
打开一个交互式配方仪表盘。否则：
```powershell
# 安装依赖
uv sync
# 安装 Playwright 浏览器
playwright install chromium
# 启动后端（端口 10780）
uv run browser-mcp --serve
# 启动前端（端口 10781）- 单独的终端
cd webapp && npm install && npm run dev
```
更多详细信息请参阅：[INSTALL.md](INSTALL.md)
---
## 工具参考
### 浏览器自动化
```python
# 导航并提取
await browse_page("https://example.com")
# → {"title": "...", "text": "...", "url": "...", "status": 200}
# 点击和交互
await click_element("button#submit")
await fill_input("#search", "hello world")
await press_key("Enter")
# 截图
await screenshot()
# → {"screenshot_b64": "iVBORw0KGgo..."}
# CLI 模式（无需 Playwright 会话）
await browse_url_cli("https://example.com", browser="chrome")
# 检测已安装的浏览器
await list_browsers()
# → {"browsers": {"chrome": {"installed": true, "path": "..."}, ...}}
```
### 书签管理
```python
# 列出 Chrome 书签
await browser_bookmarks(operation="list_bookmarks", browser="chrome")
# 列出 Firefox 书签
await browser_bookmarks(operation="list_bookmarks", browser="firefox")
# 添加书签
await browser_bookmarks(
operation="add_bookmark",
browser="chrome",
url="https://example.com",
title="Example",
)
# 搜索
await browser_bookmarks(operation="search", browser="firefox", search_query="python")
# 查找重复项（仅 Firefox）
await browser_bookmarks(operation="find_duplicates", browser="firefox")
# 从 Firefox 同步书签到 Chrome
await browser_bookmarks(
operation="sync_bookmarks",
browser="firefox",
target_browser="chrome",
)
# 导出 Firefox 书签
await browser_bookmarks(operation="export_bookmarks", browser="firefox", export_format="json")
# 查找遗忘的书签（1 年未访问）
await browser_bookmarks(
operation="find_forgotten_bookmarks",
browser="firefox",
age_days=365,
)
```
### 工作流工具
| 工具 | 描述 |
|------|-------------|
| `morning_briefing(config_name)` | 可配置的每日页面例行程序，带有 4 个内置配置文件 |
| `browse_items(items_json, task)` | 浏览链接列表（来自 aiwatcher/arxiv/gitops），带有摘要 |
| `browse_workflow(task, initial_url)` | 从自然语言任务的多步骤代理浏览 |
**晨间简报配置文件**（定义在 `conf/morning_pages.json` 中）：
| 配置文件 | 页面 | 集成 |
|---------|-------|-------------|
| `default` | HN + GitHub Trending | AIWatcher, GitHub 仓库 |
| `dev` | HN + Python Trending + Lobsters | AIWatcher, arXiv cs.AI/cs.SE |
| `research` | arXiv cs.AI + r/MachineLearning | AIWatcher, arXiv cs.AI/LG/CV/ML |
| `fleet` | Sandra 的仓库 | AIWatcher, 6 个 fleet 仓库 |
**与 fleet MCP 服务器链接：**
```python
# 1. 从 aiwatcher-mcp 获取顶部项目
items = await aiwatcher.get_top_items(hours=24, limit=5)
# 2. 浏览它们
await browse_items(items_json=items, task="What's interesting?")
# 1. 获取 GitHub 问题
issues = await gitops.issue_list(owner="sandraschi", repo="browser-mcp")
# 2. 浏览问题页面
await browse_items(items_json=issues)
```
### 完整操作列表
| 操作 | Chrome | Firefox | Edge | Brave |
|-----------|:------:|:-------:|:----:|:-----:|
| list_bookmarks | ✓ | ✓ | ✓ | ✓ |
| get_bookmark | ✓ | ✓ | ✓ | ✓ |
| add_bookmark | ✓ | ✓ | ✓ | ✓ |
| edit_bookmark | ✓ | ✓ | ✓ | ✓ |
| delete_bookmark | ✓ | ✓ | ✓ | ✓ |
| search / search_bookmarks | ✓ | ✓ | ✓ | ✓ |
| sync_bookmarks | ✓ | ✓ | ✓ | ✓ |
| find_duplicates | — | ✓ | — | — |
| export_bookmarks | — | ✓ | — | — |
| list_tags | — | ✓ | — | — |
| find_similar_tags | — | ✓ | — | — |
| merge_tags | — | ✓ | — | — |
| clean_up_tags | — | ✓ | — | — |
| find_old_bookmarks | — | ✓ | — | — |
| find_forgotten_bookmarks | — | ✓ | — | — |
| get_bookmark_stats | — | ✓ | — | — |
| find_broken_links | — | ✓ | — | — |
| refresh_bookmarks | — | ✓ | — | — |
---
## 架构
### 浏览器控制层
| 层 | Chrome/Chromium | Firefox |
|-------|----------------|---------|
| **书签读写** | 直接 JSON 文件 | 直接 SQLite |
| **无头自动化** | Playwright（主要）+ CDP WebSocket | Playwright（主要）+ geckodriver |
| **CLI 快速操作** | `chrome --headless --dump-dom` | `firefox --headless --screenshot` |
### 端口
| 端口 | 服务 |
|------|---------|
| 10780 | 后端（FastAPI + MCP HTTP） |
| 10781 | 前端（Vite React 开发服务器） |
### 项目结构
```
browser-mcp/
├── src/browser_mcp/
│ ├── server.py # MCP 工具 + 浏览器生命周期
│ ├── app.py # FastAPI 应用，带有 /health + MCP 挂载
│ ├── config.py # 基于环境的设置
│ ├── __main__.py # CLI 入口点（stdio / HTTP）
│ └── bookmarks/ # 书签管理后端
│ ├── portmanteau.py # 主要 browser_bookmarks MCP 工具
│ ├── firefox_bookmarks.py # Firefox SQLite 后端
│ ├── chromium_common.py # Chrome/Edge/Brave JSON 后端
│ ├── sync.py # 跨浏览器同步
│ └── firefox/ # 13 个子模块（db, status, utils 等）
├── webapp/ # React + Vite 仪表盘（端口 10781）
│ ├── src/
│ │ ├── pages/Dashboard.tsx
│ │ └── pages/Bookmarks.tsx
│ └── package.json
└── justfile
```
---
## 配置
| 环境变量 | 默认值 | 描述 |
|---------|---------|-------------|
| `BROWSER_MCP_HOST` | 127.0.0.1 | HTTP 绑定地址 |
| `BROWSER_MCP_PORT` | 10780 | HTTP 后端端口 |
| `BROWSER_MCP_FRONTEND_PORT` | 10781 | Vite 前端端口 |
| `BROWSER_HEADLESS` | true | 运行 Playwright 无头 |
| `MCP_TRANSPORT` | — | 设置为 `http` 以使用 HTTP 模式 |
---
## 运行
```powershell
# stdio 模式（Claude Desktop，MCP 客户端）
uv run browser-mcp --stdio
# HTTP 模式（网页仪表盘 + API）
uv run browser-mcp --serve
# 调试模式
uv run browser-mcp --serve --debug
```
---
## 更新日志
请参阅 [CHANGELOG.md](CHANGELOG.md)。
---
## 许可证
MIT
