Twolven MCP Server Puppeteer Py

🚀 使用 Playwright 的 Puppeteer MCP 服務器（Python 實現）

這是一個基於 Model Context Protocol 的服務器，藉助 Playwright（Python 中的 Puppeteer 等價工具），為大語言模型賦予了瀏覽器自動化能力。它能讓 LLM 在真實的瀏覽器環境裡與網頁交互、截取屏幕並執行 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 桌面配置

將以下內容添加到 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 服務器！如需幫助或反饋，請聯繫維護團隊。