Puppeteer MCP Server (Python Implementation)

Puppeteer MCP 服务（Python 实现）

一个使用 Playwright（相当于 Python 版 Puppeteer）提供浏览器自动化功能的模型上下文协议服务。此服务可让大模型与网页交互、截取屏幕截图，并在真实浏览器环境中执行 JavaScript。

概述

此 Python 实现提供了 TypeScript 版本的稳定替代方案，在提供相同功能的同时，改进了错误处理和日志记录。它使用 Playwright（相当于 Python 版 Puppeteer），提供强大的浏览器自动化功能。

主要功能

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

前提条件

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

安装

1. 安装所需的软件包：

pip install -r requirements.txt

2. 安装 Playwright 浏览器：

playwright install

用法

启动服务

直接运行服务：

python puppeteer_server.py

Claude Desktop 配置

将以下内容添加到 Claude 配置文件中：

{
  "mcpServers": {
    "puppeteer": {
      "command": "python",
      "args": ["path/to/puppeteer.py"]
    }
  }
}

可用工具

puppeteer_navigate

在浏览器中导航至任意 URL。

{
  "name": "puppeteer_navigate",
  "arguments": {
    "url": "https://example.com",
    "timeout": 60000  // optional, defaults to 60000ms
  }
}

puppeteer_screenshot

截取整个页面或指定元素的屏幕截图。

{
  "name": "puppeteer_screenshot",
  "arguments": {
    "name": "my_screenshot",
    "selector": "#specific-element",  // optional
    "width": 1280,  // optional, default: 1280
    "height": 720,  // optional, default: 720
    "timeout": 30000  // optional, defaults to 30000ms
  }
}

puppeteer_click

点击页面上的元素。

{
  "name": "puppeteer_click",
  "arguments": {
    "selector": ".button-class",
    "timeout": 30000  // optional, defaults to 30000ms
  }
}

puppeteer_fill

填写输入字段。

{
  "name": "puppeteer_fill",
  "arguments": {
    "selector": "#input-id",
    "value": "text to fill",
    "timeout": 30000  // optional, defaults to 30000ms
  }
}

puppeteer_evaluate

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

{
  "name": "puppeteer_evaluate",
  "arguments": {
    "script": "document.title",
    "timeout": 30000  // optional, defaults to 30000ms
  }
}

错误处理

此服务针对常见情况提供详细的错误信息：

• 导航失败
• 未找到元素
• 超时错误
• JavaScript 执行错误
• 截取屏幕截图失败

日志记录

此服务实现了全面的日志记录，并设有不同级别：

• INFO：标准操作
• ERROR：操作失败
• DEBUG：详细的执行信息

注意事项

• 浏览器以非无头模式启动，便于调试
• 默认视口大小为 1280x720
• 所有超时时间均可配置
• 控制台日志会被捕获并保存
• 屏幕截图会以 base64 编码保存在内存中

贡献

欢迎贡献！提交拉取请求前，请阅读仓库的贡献指南。

作者

Todd Wolven - 首席 AI 软件开发人员和开源 GenAI 工程师

许可证

本项目采用 Apache 2.0 许可证授权，详情请参阅 LICENSE 文件。