Playwright MCP

Playwright MCP 是由 Microsoft 官方維護的 MCP Server，提供瀏覽器自動化功能。它是 GitHub 上最受歡迎的 MCP Server，擁有 12K+ stars。

為什麼選擇 Playwright MCP？

特點	說明
結構化操作	使用 Accessibility Tree，不需要截圖或視覺模型
快速輕量	純結構化資料，比截圖方式效率高
可視化操作	在可見的瀏覽器視窗中操作，你可以看到 Claude 在做什麼
跨瀏覽器	支援 Chromium、Firefox、WebKit
認證友善	你可以手動登入，Claude 繼續使用你的 session

傳統方式（截圖）：
Claude → 截圖 → 視覺分析 → 猜測元素位置 → 點擊
                            ↑
                      容易出錯、效率低

Playwright MCP（Accessibility Tree）：
Claude → 讀取結構化 DOM → 精準定位元素 → 點擊
                            ↑
                      快速、準確、可靠

安裝方式

方法 1：Claude Code CLI（推薦）

claude mcp add playwright -- npx @playwright/mcp@latest

方法 2：手動 JSON 設定

在 ~/.claude.json 或 .mcp.json 中加入：

macOS / Linux：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

Windows（使用 cmd）：

{
  "mcpServers": {
    "playwright": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@playwright/mcp@latest"]
    }
  }
}

Windows 注意事項

Claude Code 在 Windows 預設使用 git bash，需要改用 cmd。

瀏覽器安裝

Playwright MCP 會在首次使用時自動安裝瀏覽器。如果需要手動安裝：

npx playwright install chromium

使用方式

基本操作

在 Claude Code 中使用 Playwright：

Use playwright mcp to open https://example.com

明確指定 MCP

首次使用時，建議明確說 "playwright mcp"，否則 Claude 可能會嘗試用 Bash 執行 Playwright。

常見操作指令

開啟網頁：

Use playwright mcp to navigate to https://github.com

取得頁面快照（推薦）：

Use playwright mcp to take a snapshot of the current page

截圖：

Use playwright mcp to take a screenshot

點擊元素：

Use playwright mcp to click the "Sign in" button

填寫表單：

Use playwright mcp to fill the email field with "[email protected]"

按鍵操作：

Use playwright mcp to press Enter

提供的工具

Playwright MCP 提供豐富的工具：

導航

工具	說明
browser_navigate	導航到指定 URL
browser_navigate_back	回到上一頁
browser_tabs	管理分頁（列出、新增、關閉、切換）

互動

工具	說明
browser_click	點擊元素
browser_type	在輸入框輸入文字
browser_fill_form	填寫多個表單欄位
browser_select_option	選擇下拉選項
browser_hover	滑鼠懸停
browser_drag	拖放操作
browser_press_key	按下鍵盤按鍵
browser_file_upload	上傳檔案

擷取

工具	說明
browser_snapshot	取得頁面的 Accessibility Tree（推薦）
browser_take_screenshot	截圖
browser_console_messages	取得 console 訊息
browser_network_requests	取得網路請求

其他

工具	說明
browser_evaluate	執行 JavaScript
browser_handle_dialog	處理對話框（alert、confirm、prompt）
browser_wait_for	等待特定文字出現或消失
browser_resize	調整視窗大小
browser_close	關閉瀏覽器

認證處理

Playwright MCP 使用可見的瀏覽器視窗，認證非常簡單：

1. 讓 Claude 開啟登入頁面
2. 你自己輸入帳號密碼登入
3. 告訴 Claude 繼續下一步

Cookies 會在 session 期間保持。

保留登入狀態

使用 --user-data-dir 參數保留瀏覽器資料：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "-y",
        "@playwright/mcp@latest",
        "--user-data-dir=~/.playwright-profile"
      ]
    }
  }
}

這樣即使重啟 Claude Code，登入狀態也會保留。

進階設定

指定瀏覽器

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest", "--browser=firefox"]
    }
  }
}

支援的瀏覽器：chromium（預設）、firefox、webkit

Headless 模式

在沒有 GUI 的環境（如 CI/CD）中使用：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest", "--headless"]
    }
  }
}

設定 Viewport

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "-y",
        "@playwright/mcp@latest",
        "--viewport-size=1920,1080"
      ]
    }
  }
}

使用場景

E2E 測試

Use playwright mcp to:
1. Open http://localhost:3000
2. Click the "Sign Up" button
3. Fill the registration form with test data
4. Submit the form
5. Verify the welcome page loads
6. Take a screenshot

網頁資料擷取

Use playwright mcp to:
1. Open https://example.com/products
2. Take a snapshot
3. Extract all product names and prices
4. Save to products.json

UI 驗證

Use playwright mcp to:
1. Open http://localhost:3000
2. Verify the navigation menu contains these items: Home, About, Contact
3. Click each item and verify the page loads correctly
4. Report any broken links

視覺回歸測試

Use playwright mcp to:
1. Open the homepage
2. Take a screenshot named "homepage-current.png"
3. Compare with the baseline screenshot

與 Chrome DevTools MCP 的差異

特點	Playwright MCP	Chrome DevTools MCP
維護者	Microsoft	Google
重點	自動化操作	除錯和效能分析
瀏覽器支援	Chromium、Firefox、WebKit	Chrome only
效能分析	基本	進階（Performance trace）
使用情境	E2E 測試、UI 操作	除錯、效能優化

建議：兩者可以同時安裝，根據需求選擇使用。

驗證安裝

在 Claude Code 中執行：

/mcp

應該會看到 playwright 顯示為 connected。

測試是否正常運作：

Use playwright mcp to open https://example.com and take a snapshot

故障排除

瀏覽器無法啟動

1. 確認已安裝瀏覽器：

   npx playwright install chromium

2. 檢查系統是否支援 GUI：

   • Linux：需要 X11 或 Wayland
   • WSL：需要 WSLg（Windows 11）或 X server

3. 嘗試 headless 模式（見上方設定）

Windows 上的問題

Claude Code 在 Windows 預設使用 git bash，需要改用 cmd：

{
  "mcpServers": {
    "playwright": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@playwright/mcp@latest"]
    }
  }
}

操作失敗

1. 使用 snapshot 而非 screenshot：snapshot 提供結構化資料，更可靠
2. 等待頁面載入：在操作前讓 Claude 等待
3. 使用更具體的選擇器：描述元素時盡量具體

最佳實踐

1. 優先使用 Snapshot

❌ 不好：Take a screenshot and analyze it
✅ 好：Take a snapshot of the current page

Snapshot 提供結構化的 Accessibility Tree，比截圖更可靠。

2. 描述清楚目標元素

❌ 不好：Click the button
✅ 好：Click the button with text "Submit Order"
✅ 好：Click the primary button in the checkout form

3. 分步驟執行

❌ 不好：Fill the entire form and submit
✅ 好：
1. Take a snapshot to see the form structure
2. Fill the email field
3. Fill the password field
4. Click the submit button
5. Take a snapshot to verify the result

4. 處理認證網站

讓自己手動登入，然後讓 Claude 繼續操作：

1. Use playwright mcp to open https://dashboard.example.com/login
2. [你手動登入]
3. 告訴 Claude：I've logged in, please continue

參考資源

• Playwright MCP GitHub
• Playwright 官方文件
• Simon Willison 的教學
• Playwright Skill for Claude Code

下一步

• Chrome DevTools MCP - 進階瀏覽器除錯
• shadcn MCP - UI 元件查詢
• Supabase MCP - 資料庫操作