# DrissionPage MCP 浏览器自动化服务
基于 [DrissionPage](https://github.com/g1879/DrissionPage) 的 MCP (Model Context Protocol) 服务器，为 AI 模型提供强大的浏览器自动化和数据抓取功能。
## 特性
- 🌐 **浏览器自动化**：完整的浏览器控制能力（导航、点击、输入等）
- 📄 **网页转 Markdown**：智能将网页内容转换为 Markdown 格式
- 📊 **数据抓取**：结构化提取网页数据（表格、列表等）
- 🔧 **混合粒度**：提供基础操作和高级封装两种工具集
- 🎯 **单例模式**：高效管理单个浏览器实例
- 👀 **可视化调试**：默认有头模式，方便观察操作过程
## 安装
1. 克隆或下载本项目
2. 安装依赖：
```bash
cd drissionpage_mcp
pip install -r requirements.txt
```
## 快速开始
### 方式 1：直接运行测试
```bash
# 运行测试示例，验证功能
python test_example.py
```
### 方式 2：启动 MCP 服务器
```bash
python server.py
```
服务器将通过标准输入/输出与 MCP 客户端通信。
### 方式 3：配置 MCP 客户端
如果您使用支持 MCP 的 AI 工具（如 Claude Desktop、Cursor 等），可以在配置文件中添加：
**Claude Desktop 配置示例** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"drissionpage": {
"command": "python",
"args": ["/Users/Desktop/drissionpage_mcp/server.py"]
}
}
}
```
配置后重启客户端，AI 模型即可调用浏览器自动化功能。
### 使用示例
#### 示例 1：访问网页并保存为 Markdown
```python
# AI 模型可以通过 MCP 调用以下工具链：
1. init_browser() # 启动浏览器
2. navigate(url="https://news.ycombinator.com") # 访问网页
3. page_to_markdown(file_path="hn_news.md") # 保存为 Markdown
4. close_browser() # 关闭浏览器
```
#### 示例 2：自动填写表单
```python
1. init_browser()
2. navigate(url="https://example.com/login")
3. input_text(selector="#username", text="user")
4. input_text(selector="#password", text="pass")
5. click_element(selector="button[type='submit']")
6. wait_for_element(selector=".dashboard", timeout=10)
7. page_to_markdown(file_path="dashboard.md")
```
#### 示例 3：数据抓取
```python
1. init_browser()
2. navigate(url="https://example.com/data")
3. extract_table_data(selector="table.data-table", format="json")
4. close_browser()
```
## 工具列表
### 浏览器管理
- `init_browser`: 初始化浏览器实例
- `get_browser_status`: 获取浏览器状态
- `close_browser`: 关闭浏览器
### 基础操作
- `navigate`: 导航到 URL
- `find_elements`: 查找页面元素
- `click_element`: 点击元素
- `input_text`: 输入文本
- `get_element_text`: 获取元素文本
- `get_element_attribute`: 获取元素属性
- `wait_for_element`: 等待元素出现
- `scroll_page`: 滚动页面
- `take_screenshot`: 截图
- `execute_javascript`: 执行 JS 代码
### 高级功能
- `page_to_markdown`: 网页转 Markdown（核心功能）
- `extract_table_data`: 提取表格数据
- `smart_extract`: 智能数据抓取
- `fill_form`: 自动填写表单
- `handle_infinite_scroll`: 处理无限滚动
- `manage_cookies`: Cookie 管理
- `switch_to_tab`: Tab 页切换
## 技术架构
```
drissionpage_mcp/
├── __init__.py # 包初始化
├── server.py # MCP 服务器主入口
├── browser.py # 浏览器单例管理器
├── tools/ # 工具集
│ ├── __init__.py
│ ├── basic.py # 基础操作工具
│ ├── advanced.py # 高级功能工具
│ └── markdown.py # Markdown 转换工具
├── requirements.txt # 依赖列表
└── README.md # 本文档
```
## 依赖项
- **DrissionPage**: 浏览器自动化核心库
- **mcp**: Model Context Protocol 实现
- **markdownify / html2text**: HTML 转 Markdown
- **beautifulsoup4**: HTML 解析
- **lxml**: 高性能 XML/HTML 解析
## 开发指南
### 添加新工具
1. 在相应的工具文件（`basic.py`、`advanced.py` 等）中定义函数
2. 在 `tools/__init__.py` 中导出
3. 在 `server.py` 中注册到 MCP 服务器
### 错误处理
所有工具函数都应返回统一的格式：
```python
{
"success": True/False,
"data": {...}, # 成功时的数据
"error": "...", # 失败时的错误信息
}
```
## 使用注意
1. **浏览器单例**：同一时间只能有一个浏览器实例，适合顺序执行任务
2. **资源释放**：使用完毕后请调用 `close_browser()` 释放资源
3. **超时控制**：所有操作都有超时参数，避免无限等待
4. **调试模式**：默认有头模式便于调试，生产环境可配置为无头模式
5. **网络延迟**：根据网络情况调整 `timeout` 参数
6. **选择器优化**：优先使用 CSS 选择器，性能更好
## 常见问题
### Q: 如何切换为无头模式？
A: 调用 `init_browser(headless=true)` 即可。
### Q: 支持哪些浏览器？
A: 支持 Chromium 内核浏览器（Chrome、Edge 等）。
### Q: 如何处理需要登录的网站？
A: 使用 `fill_form` 工具自动填写表单，或使用 `manage_cookies` 设置已保存的 Cookie。
### Q: 可以同时打开多个标签页吗？
A: 可以，使用 `switch_to_tab(action="new")` 创建新标签页。
### Q: Markdown 转换质量如何提升？
A: 启用 `extract_main=true` 和 `remove_ads=true` 选项，只保留主要内容。
## 高级用法
### 自定义浏览器配置
```python
init_browser(
headless=False,
window_size=[1920, 1080],
user_agent="Custom User Agent",
proxy="http://proxy.example.com:8080"
)
```
### 批量数据抓取
```python
# 1. 访问列表页
navigate(url="https://example.com/articles")
# 2. 处理懒加载
handle_infinite_scroll(max_scrolls=10, check_selector=".article")
# 3. 提取所有文章
smart_extract(
selector=".article",
fields={
"title": "h2.title",
"summary": "p.summary",
"link": "a.read-more"
}
)
```
### 复杂表单自动化
```python
fill_form(
fields={
"#email": "user@example.com",
"#password": "secure_password",
"#country": "China", # 下拉框
"#agree": True, # 复选框
"#newsletter": False
},
submit_selector="button.submit"
)
```
## 性能优化建议
1. **减少等待时间**：合理设置 `timeout` 和 `wait_after` 参数
2. **批量操作**：使用 `smart_extract` 一次性提取多个元素
3. **缓存页面**：避免重复访问同一页面
4. **并发处理**：对于独立任务，可启动多个 MCP 服务器实例
## 文档资源
- **详细使用指南**：查看 `USAGE_GUIDE.md`
- **测试示例**：查看 `test_example.py`
- **DrissionPage 文档**：https://DrissionPage.cn
- **MCP 协议规范**：https://modelcontextprotocol.io/
## 许可证
本项目遵循 MIT 许可证。
## 致谢
- [DrissionPage](https://github.com/g1879/DrissionPage) - 强大的 Python 网页自动化工具
- [Model Context Protocol](https://modelcontextprotocol.io/) - AI 模型工具调用标准