JinDaGe - twolven_mcp-server-puppeteer-py MCP Details

article

README

🚀 使用 Playwright 的 Puppeteer MCP 服务器（Python 实现）

这是一个基于 Model Context Protocol 的服务器，借助 Playwright（Python 中的 Puppeteer 等价工具），为大语言模型赋予浏览器自动化能力。它能让 LLM 在真实浏览器环境中与网页交互、截取屏幕并执行 JavaScript 代码。

🚀 快速开始

此 Python 实现提供了稳定且可靠的替代方案，与 TypeScript 版本功能相同，但错误处理和日志记录更加完善。它使用 Playwright，这是 Python 的 Puppeteer 等价物，提供强大的浏览器自动化能力。

✨ 主要特性

浏览器完全自动化
页面导航
截图捕获（整页或元素）
表单交互（点击和填写）
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"]
    }
  }
}

可用工具

基础用法

以下是各个工具的基础使用示例：

puppeteer_navigate：在浏览器中导航到任意 URL。

{
  "name": "puppeteer_navigate",
  "arguments": {
    "url": "https://example.com",
    "timeout": 60000  // 可选，默认为 60000ms
  }
}

puppeteer_screenshot：捕获整页或特定元素的截图。

{
  "name": "puppeteer_screenshot",
  "arguments": {
    "name": "my_screenshot",
    "selector": "#specific-element",  // 可选
    "width": 1280,  // 可选，默认：1280
    "height": 720,  // 可选，默认：720
    "timeout": 30000  // 可选，默认为 30000ms
  }
}

puppeteer_click：点击页面上的元素。

{
  "name": "puppeteer_click",
  "arguments": {
    "selector": ".button-class",
    "timeout": 30000  // 可选，默认为 30000ms
  }
}

puppeteer_fill：填写输入字段。

{
  "name": "puppeteer_fill",
  "arguments": {
    "selector": "#input-id",
    "value": "要填充的文本",
    "timeout": 30000  // 可选，默认为 30000ms
  }
}

puppeteer_evaluate：在浏览器控制台中执行 JavaScript。

{
  "name": "puppeteer_evaluate",
  "arguments": {
    "script": "document.title",
    "timeout": 30000  // 可选，默认为 30000ms
  }
}

高级用法

填写表单并捕获截图

from playwright.sync_playwright import sync_playwright

def main():
    with sync_playwright() as p:
        browser = p.chromium.launch()
        page = browser.new_page()
        
        # 导航到页面
        page.goto('https://example.com')
        
        # 填写表单
        page.fill('#username', 'admin')
        page.fill('#password', 'secret')
        
        # 提交表单
        page.click('button[type="submit"]')
        
        # 捕获截图
        page.screenshot(path='screenshot.png', quality=100)
        
        browser.close()

if __name__ == "__main__":
    main()

📚 详细文档

错误处理

服务器提供详细的错误消息，涵盖常见场景：

导航失败
元素未找到
超时错误
JavaScript 执行失败

日志记录

通过控制台输出进行调试和监控，便于排查问题。

项目结构

puppeteer_server/
├── server.py        # 主服务器文件
├── utils.py         # 辅助函数
├── requirements.txt # 依赖管理
└── README.md        # 项目文档

🤝 贡献指南

欢迎贡献！请 fork 本仓库并提交 PR。

📄 许可证

[此处插入许可证信息]

感谢您使用 Puppeteer MCP 服务器！如需帮助或反馈，请联系维护团队。

twolven_mcp-server-puppeteer-py