DrissionPage MCP 浏览器自动化服务

基于 DrissionPage 的 MCP (Model Context Protocol) 服务器，为 AI 模型提供强大的浏览器自动化和数据抓取功能。

特性

• 🌐 浏览器自动化：完整的浏览器控制能力（导航、点击、输入等）
• 📄 网页转 Markdown：智能将网页内容转换为 Markdown 格式
• 📊 数据抓取：结构化提取网页数据（表格、列表等）
• 🔧 混合粒度：提供基础操作和高级封装两种工具集
• 🎯 单例模式：高效管理单个浏览器实例
• 👀 可视化调试：默认有头模式，方便观察操作过程

安装

1. 克隆或下载本项目

2. 安装依赖：

cd drissionpage_mcp
pip install -r requirements.txt

快速开始

方式 1：直接运行测试

# 运行测试示例，验证功能
python test_example.py

方式 2：启动 MCP 服务器

python server.py

服务器将通过标准输入/输出与 MCP 客户端通信。

方式 3：配置 MCP 客户端

如果您使用支持 MCP 的 AI 工具（如 Claude Desktop、Cursor 等），可以在配置文件中添加：

Claude Desktop 配置示例 (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "drissionpage": {
      "command": "python",
      "args": ["/Users/Desktop/drissionpage_mcp/server.py"]
    }
  }
}

配置后重启客户端，AI 模型即可调用浏览器自动化功能。

使用示例

示例 1：访问网页并保存为 Markdown

# 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：自动填写表单

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：数据抓取

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 服务器

错误处理

所有工具函数都应返回统一的格式：

{
    "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 选项，只保留主要内容。

高级用法

自定义浏览器配置

init_browser(
    headless=False,
    window_size=[1920, 1080],
    user_agent="Custom User Agent",
    proxy="http://proxy.example.com:8080"
)

批量数据抓取

# 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"
    }
)

复杂表单自动化

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 - 强大的 Python 网页自动化工具
• Model Context Protocol - AI 模型工具调用标准