Playwright Plus Python MCP

🚀 Playwright Server MCP

一個基於Playwright的MCP服務器，提供瀏覽器自動化能力。該服務器可實現筆記存儲、提示生成等功能，同時具備豐富的Playwright工具，能滿足各種瀏覽器交互需求。

🚀 快速開始

📦 安裝

Claude Desktop配置

• MacOS：~/Library/Application\ Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%/Claude/claude_desktop_config.json

"mcpServers": {
  "playwright-server": {
    "command": "uv",
    "args": [
      "--directory",
      "C:\\Users\\xxxxx\\Documents\\project\\python\\mcp\\playwright-server",
      "run",
      "playwright-server"
    ]
  }
}

"mcpServers": {
  "playwright-server": {
    "command": "uvx",
    "args": [
      "playwright-server"
    ]
  }
}

✨ 主要特性

🔍 組件

📚 資源

服務器實現了簡單的筆記存儲系統：

• 自定義note:// URI方案用於訪問單個筆記。
• 每個筆記資源具有名稱、描述和text/plain MIME類型。

💡 提示

服務器提供單個提示功能：

• summarize-notes：創建所有存儲筆記的摘要。
  • 可選style參數控制詳細程度（brief/detailed）。
  • 生成結合所有當前筆記與樣式偏好的提示。

🛠️ 工具

服務器實現以下Playwright相關工具：

會話與導航

• playwright_new_session：創建新的瀏覽器會話並打開瀏覽器窗口。
  • 可選url參數（字符串），指定初始訪問網址，不填則只打開瀏覽器。
• playwright_navigate：導航到指定網址。
  • 需要url參數（字符串），如不包含http或https前綴將自動添加https://。
  • 如果沒有活躍的瀏覽器會話，會自動創建一個新會話。

頁面交互與獲取內容

• playwright_screenshot：對當前頁面或特定元素進行截圖。
  • 需要name參數（字符串），截圖文件名稱，不需要包含擴展名。
  • 可選selector參數（字符串），CSS選擇器用於指定要截圖的頁面元素，不填則截取整個頁面。
• playwright_evaluate：在瀏覽器控制檯中執行JavaScript代碼。
  • 需要script參數（字符串），需要在瀏覽器中執行的JavaScript代碼。
• playwright_get_text_content：獲取當前頁面中所有可見元素的文本內容。
  • 無需參數。
  • 智能過濾重複內容，只返回有意義的文本。
• playwright_get_html_content：獲取頁面中指定元素的HTML內容。
  • 需要selector參數（字符串），CSS選擇器用於定位需要獲取HTML內容的頁面元素。

高級交互操作

• playwright_action：支持豐富的元素選擇與交互方式。
  • 必需參數：
    • by：選擇元素方式，支持get_by_text、get_by_placeholder、get_by_label、get_by_role等。
    • by_value：選擇元素的值。
    • action：操作類型，如fill、click、dblclick、hover、check等。
  • 可選參數：
    • value：操作的值。
    • force：是否強制執行動作。
    • delay：按鍵之間的延遲（毫秒）。
    • 以及更多專用參數，參見代碼文檔。

🔧 技術細節

⚙️ 配置

系統要求

• Python 3.10+
• Playwright 1.44+

🚧 開發

構建與發佈

準備發佈包：

1. 同步依賴並更新鎖定文件：

uv sync

2. 構建包分發：

uv build

這將在dist/目錄中創建源代碼和wheel分發。

3. 發佈到PyPI：

uv publish

注意：您需要通過環境變量或命令參數設置PyPI憑據：

• 令牌：--token或UV_PUBLISH_TOKEN
• 或用戶名/密碼：--username/UV_PUBLISH_USERNAME和--password/UV_PUBLISH_PASSWORD

調試

由於MCP服務器通過stdio運行，調試可能具有挑戰性。為獲得最佳調試體驗，我們強烈推薦使用MCP Inspector。

您可以通過npm使用以下命令啟動MCP Inspector：

npx @modelcontextprotocol/inspector uv --directory C:\Users\xxxxx\Documents\project\python\mcp\playwright-server run playwright-server

啟動後，Inspector將顯示一個URL，您可以在瀏覽器中訪問該URL開始調試。

💻 使用示例

基礎用法

# 創建會話並導航到指定網址
await playwright_navigate(url="example.com")

# 截取整個頁面
await playwright_screenshot(name="fullpage")

# 截取特定元素
await playwright_screenshot(name="logo", selector=".logo")

高級用法

# 點擊文本匹配的按鈕
await playwright_action(by="get_by_text", by_value="登錄", action="click")

# 填充表單字段
await playwright_action(by="get_by_placeholder", by_value="用戶名", action="fill", value="test@example.com")

# 檢查元素是否可見
await playwright_action(by="get_by_test_id", by_value="submit-button", action="is_visible")