MCP Server Puppeteer Py

🚀 木偶师 MCP 服务器（Python 实现）

这是一个具备浏览器自动化能力的模型上下文协议服务器，借助 Playwright（相当于 Python 版的 Puppeteer）实现。该服务器让大语言模型（LLM）能与网页交互、截取屏幕截图并执行 JavaScript，可在真实的浏览器环境中运行。

🚀 快速开始

此 Python 实现提供了稳定的替代方案，与 TypeScript 版本相比，功能相同，但在错误处理和日志记录方面表现更佳。它使用 Playwright，为 Python 提供强大的浏览器自动化功能。

✨ 主要特性

• 浏览器完全自动化
• 页面导航
• 截取屏幕截图（全页或元素）
• 表单交互（点击和填写）
• JavaScript 执行
• 控制台日志监控
• 可配置超时
• 详细的错误处理
• 全面的日志记录

📦 安装指南

前提条件

• Python 3.8+
• pip（Python 包安装程序）

安装步骤

1. 安装所需的包：

pip install -r requirements.txt

2. 安装 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 环境中也能高效地进行网页交互操作。