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 環境中也能高效地進行網頁交互操作。