Playwright MCP Server

🚀 Playwright MCP 服務器

這個項目是一個使用 Model Context Protocol (MCP) 提供 Playwright 網頁內容檢索功能的服務器，藉助 Playwright 強大的自動化能力，構建了一個靈活且可擴展的平臺，方便其他服務或模型調用其功能，對於需要進行網頁自動化測試、數據抓取或其他類似任務的開發者來說十分實用。

English | 日本語

🚀 快速開始

本項目是一個藉助 Model Context Protocol (MCP) 來提供 Playwright 網頁內容檢索功能的服務器。

✨ 主要特性

• 頁面導航：可實現頁面的導航操作。
• 整個頁面內容檢索：能夠檢索整個頁面的內容。
• 可見內容檢索：支持對當前可見內容進行檢索。
• 交互元素檢測：可以檢測頁面上的交互元素。
• 鼠標操作模擬：能模擬鼠標的移動、點擊、滾動和拖放等操作。
• 測試用例回聲功能：具備測試用例回聲工具。

📦 安裝指南

使用 Smithery 自動安裝

通過 Smithery 可自動為 Claude Desktop 安裝 Playwright MCP Server：

npx -y @smithery/cli install @showfive/playwright-mcp-server --client claude

手動安裝

npm install

💻 使用示例

啟動服務器

npm run build
npm start

MCP 工具

以下工具可供使用：

1. navigate
   • 功能：導航到指定 URL。
   • 參數：{ url: string }
   • 返回：導航結果
2. get_all_content
   • 功能：檢索整個頁面的內容。
   • 參數：無
   • 返回：頁面中的所有文本內容
3. get_visible_content
   • 功能：檢索當前可見內容。
   • 參數：{ minVisiblePercentage?: number }
   • 返回：可見的文本內容
4. get_interactive_elements
   • 功能：獲取交互元素的位置信息（按鈕、鏈接等）。
   • 參數：無
   • 返回：頁面上交互元素的座標和邊界信息
5. move_mouse
   • 功能：將鼠標指針移動到指定座標。
   • 參數：{ x: number, y: number }
   • 返回：操作結果
6. mouse_click
   • 功能：在指定座標執行鼠標點擊。
   • 參數：{ x: number, y: number, button?: "left" | "right" | "middle", clickCount?: number }
   • 返回：點擊操作結果
7. mouse_wheel
   • 功能：執行鼠標滾輪滾動。
   • 參數：{ deltaY: number, deltaX?: number }
   • 返回：滾動操作結果
8. drag_and_drop
   • 功能：執行拖放操作。
   • 參數：{ sourceX: number, sourceY: number, targetX: number, targetY: number }
   • 返回：拖放操作結果
9. echo
   • 功能：測試用例回聲工具。
   • 參數：{ message: string }
   • 返回：發送的消息

📚 詳細文檔

開發

運行測試

# 運行所有測試
npm test

# 以 watch 模式運行測試
npm run test:watch

# 生成覆蓋報告
npm run test:coverage

測試結構

• tools/*.test.ts：每個工具的功能測試
• mcp-server.test.ts：MCP 服務器的整體測試

實現特點

• 內容獲取：能高效地檢索頁面內容，支持可見和不可見內容。
• 交互操作：可模擬鼠標移動、點擊和滾動等用戶操作。
• 錯誤處理：擁有完善的異常處理機制，確保服務器穩定運行。
• 配置靈活性：支持無頭模式、自定義用戶代理等配置選項。

⚠️ 重要提示

1. 需要設置必要的環境變量以確保服務器正常運行。
2. 要遵循目標網站的服務條款和使用規則。
3. 需保持合理的時間間隔發送請求，避免觸發反爬機制。
4. 模擬鼠標操作時要注意頻率控制，避免被誤判為惡意攻擊。