🚀 木偶师 MCP 服务器（Python 实现）
这是一个具备浏览器自动化能力的模型上下文协议服务器，借助 Playwright（相当于 Python 版的 Puppeteer）实现。该服务器让大语言模型（LLM）能与网页交互、截取屏幕截图并执行 JavaScript，可在真实的浏览器环境中运行。
🚀 快速开始
此 Python 实现提供了稳定的替代方案，与 TypeScript 版本相比，功能相同，但在错误处理和日志记录方面表现更佳。它使用 Playwright，为 Python 提供强大的浏览器自动化功能。
✨ 主要特性
- 浏览器完全自动化
- 页面导航
- 截取屏幕截图（全页或元素）
- 表单交互（点击和填写）
- JavaScript 执行
- 控制台日志监控
- 可配置超时
- 详细的错误处理
- 全面的日志记录
📦 安装指南
前提条件
- Python 3.8+
- pip（Python 包安装程序）
安装步骤
- 安装所需的包：
pip install -r requirements.txt
- 安装 Playwright 浏览器：
playwright install
💻 使用示例
启动服务器
直接运行服务器：
python puppeteer_server.py
Claude 桌面配置
将以下内容添加到 Claude 配置文件中：
{
"mcpServers": {
"puppeteer": {
"command": "python",
"args": ["path/to/puppeteer.py"]
}
}
}
基础用法
导航到指定 URL
{
"name": "puppeteer_navigate",
"arguments": {
"url": "https://example.com",
"timeout": 60000 // 可选，默认为 60000ms
}
}
截取网页或特定元素的屏幕截图
{
"name": "puppeteer_screenshot",
"arguments": {
"name": "my_screenshot",
"selector": "#specific-element", // 可选
"width": 1280, // 可选，默认：1280
"height": 720, // 可选，默认：720
"timeout": 30000 // 可选，默认为 30000ms
}
}
点击页面上的元素
{
"name": "puppeteer_click",
"arguments": {
"selector": ".button-class",
"timeout": 30000 // 可选，默认为 30000ms
}
}
填写输入字段
{
"name": "puppeteer_fill",
"arguments": {
"selector": "#input-id",
"value": "要填充的文本",
"timeout": 30000 // 可选，默认为 30000ms
}
}
在浏览器控制台中执行 JavaScript
{
"name": "puppeteer_evaluate",
"arguments": {
"script": "document.title",
"timeout": 30000 // 可选，默认为 30000ms
}
}
🔧 技术细节
错误处理
服务器会提供详细的错误消息，涵盖以下情况：
- 导航失败
- 元素未找到
- 超时错误
日志记录
日志分为三个级别：
- INFO：正常操作的消息。
- ERROR：错误或异常的情况。
- DEBUG：详细调试信息。
默认情况下，浏览器以非无头模式运行，这对于调试非常有用。在生产环境中，可能需要切换到无头模式以提高性能。
超时配置
所有超时都是可配置的，可以根据具体需求调整等待时间，避免因网络延迟或其他问题导致脚本卡死。
这个项目提供了全面的功能和良好的文档，适合需要浏览器自动化任务的开发者使用。特别是 Playwright 的支持，确保了在 Python 环境中也能高效地进行网页交互操作。