/ 目錄 / 演練場 / Android-MCP
● 社群 CursorTouch ⚡ 即開即用

Android-MCP

作者 CursorTouch · CursorTouch/Android-MCP

透過對話操控 Android 裝置或模擬器——點擊、滑動、輸入、讀取通知——適用於 QA 自動化或產品展示。

CursorTouch 開發的 Android-MCP 封裝了 ADB,讓 MCP 客戶端能對 Android 10+ 裝置執行點擊、滑動、輸入、硬體按鍵、通知讀取與 Shell 指令操作。非常適合 UI 測試腳本建構、可重複執行的展示,或自動化繁瑣的應用程式流程。需要 ADB 和已連線的裝置或模擬器。

為什麼要用

核心特性

即時演示

實際使用效果

android.replay ▶ 就緒
0/0

安裝

選擇你的客戶端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "android": {
      "command": "uvx",
      "args": [
        "Android-MCP"
      ],
      "_inferred": true
    }
  }
}

開啟 Claude Desktop → Settings → Developer → Edit Config。儲存後重啟應用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "android": {
      "command": "uvx",
      "args": [
        "Android-MCP"
      ],
      "_inferred": true
    }
  }
}

Cursor 使用與 Claude Desktop 相同的 mcpServers 格式。專案級設定優先於全域。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "android": {
      "command": "uvx",
      "args": [
        "Android-MCP"
      ],
      "_inferred": true
    }
  }
}

點擊 Cline 側欄中的 MCP Servers 圖示,然後選 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "android": {
      "command": "uvx",
      "args": [
        "Android-MCP"
      ],
      "_inferred": true
    }
  }
}

格式與 Claude Desktop 相同。重啟 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "android",
      "command": "uvx",
      "args": [
        "Android-MCP"
      ]
    }
  ]
}

Continue 使用伺服器物件陣列,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "android": {
      "command": {
        "path": "uvx",
        "args": [
          "Android-MCP"
        ]
      }
    }
  }
}

加入 context_servers。Zed 儲存後熱重載。

claude mcp add android -- uvx Android-MCP

一行命令搞定。用 claude mcp list 驗證,claude mcp remove 移除。

使用場景

實戰用法: Android-MCP

自動化執行 Android 應用程式的冒煙測試

👤 行動裝置 QA 工程師、沒有測試框架的開發團隊 ⏱ ~30 min intermediate

何時使用: 你希望在每次發布前自動執行「應用程式開啟、登入、主畫面載入」的驗證流程。

前置條件
  • 已安裝 ADB 且裝置已連線 — Android Studio 內建 ADB;執行 adb devices 應可看到你的裝置
  • 裝置已開啟 USB 偵錯或無線偵錯 — 設定 > 開發人員選項 > USB 偵錯
步驟
  1. 擷取目前狀態
    取得 UI 狀態——我現在在哪個畫面,有哪些可見元素?✓ 已複製
    → 包含標記元素的 UI 樹狀結構
  2. 執行操作流程
    點擊「登入」按鈕,在電子郵件欄位輸入 '[email protected]',在密碼欄位輸入 'P@ss',然後送出。✓ 已複製
    → 應用程式切換至首頁
  3. 驗證結果
    確認首頁的「歡迎」橫幅是否可見。若不可見,則標記為失敗。✓ 已複製
    → 通過/失敗的判定結果

結果: 一個可腳本化的冒煙測試,能在每次建置後執行。

注意事項
  • 座標因裝置尺寸不同而改變 — 優先使用 State 工具依標籤或 id 查詢元素,再點擊回傳的座標
  • A/B 測試導致流程中斷 — 釘選建置設定,或在 QA 建置中停用實驗功能
搭配使用: github

在實機上執行可重複的產品展示

👤 銷售工程師、進行投資人展示的產品人員 ⏱ ~20 min intermediate

何時使用: 你希望在口頭說明時,讓應用程式自動操作,無需手動介入。

步驟
  1. 撰寫展示腳本
    腳本化以下 5 個步驟,每步驟間隔 3 秒:開啟應用程式、點擊探索、滑動至分類 B、點擊項目 X、截圖。✓ 已複製
    → 步驟計劃
  2. 執行預演
    開始執行。每個步驟之間暫停,讓我有時間旁白說明。✓ 已複製
    → 裝置依序執行

結果: 一個無卡頓、可重複執行的產品展示流程。

對開發裝置上的通知進行分類處理

👤 測試通知流程的開發人員 ⏱ ~10 min beginner

何時使用: 驗證推播通知是否正確送達且顯示內容正確。

步驟
  1. 讀取最近的通知
    列出目前的通知,並標記來自 com.myapp.prod 的項目。✓ 已複製
    → 已篩選的通知列表
  2. 檢查特定通知
    取得最新一則 myapp 通知的完整內容,確認是否符合預期格式。✓ 已複製
    → 與預期結果的比對差異

結果: 快速確認推播流程是否正常運作。

組合

與其他 MCP 搭配,撬動十倍槓桿

android + github

在 PR 上執行冒煙測試並回報結果

當 PR #88 有新的 APK 產出物時,安裝至已連線的裝置,執行冒煙測試流程,並將結果以留言回報至該 PR。✓ 已複製
android + filesystem

將截圖和日誌儲存為 QA 產出物

在展示流程的每個步驟後截圖,並儲存至 ./qa/2026-04-14/step-N.png。✓ 已複製

工具

此 MCP 暴露的能力

工具輸入參數何時呼叫成本
State-Tool (none) 永遠優先呼叫——先了解目前畫面內容 free
Click-Tool x: int, y: int 點擊 State 回傳的座標位置 free
Long-Click-Tool x, y, duration_ms? 開啟右鍵選單 free
Type-Tool text: str, clear_first?: bool 在目前焦點欄位中輸入文字 free
Swipe-Tool x1,y1,x2,y2, duration_ms? 滾動或執行手勢操作 free
Drag-Tool start_x,y,end_x,y 拖放操作流程 free
Press-Tool key: Back|Home|VolumeUp|... 硬體按鍵或系統導航 free
Wait-Tool ms: int 等待動畫或畫面切換完成 free
Notification-Tool (none) or package: str 檢查通知內容 free
Shell-Tool cmd: str 進階用途,如查看日誌、執行 am/pm 指令等 free (but powerful — dangerous)

成本與限制

運行它的成本

API 配額
無——全部透過 ADB 在本機執行
每次呼叫 Token 數
State 工具在畫面元素較多時,回傳的 UI 樹狀結構可能達 2-10k tokens
費用
免費
提示
請 State 依查詢條件篩選(例如「找出含有登入的按鈕」),而非傾印整個 UI 樹狀結構。

安全

權限、密鑰、影響範圍

憑證儲存: 無;ADB 信任關係存於裝置端
資料出站: 全部在本機執行;ADB 僅透過 USB 或本地 Wi-Fi 連線
切勿授予: Shell-Tool on devices with production data — it can read private files

故障排查

常見錯誤與修復

adb: device unauthorized

在裝置螢幕上接受憑證確認提示,然後重試。

驗證: adb devices
No devices found

確認 USB 偵錯已開啟,且 USB 線支援資料傳輸。若使用 WiFi,請以 adb connect 確認 ip:port 是否正確。

驗證: adb devices
Coordinates off on different screen

使用 State-Tool 取得標記元素的目前座標,而非使用硬編碼的 x,y 值。

驗證: Call State before click
Type-Tool inserts garbage characters

裝置使用非美式鍵盤;請切換為美式鍵盤,或透過 Shell-Tool 使用 adb shell input text

驗證: adb shell settings get secure default_input_method

替代方案

Android-MCP 對比其他方案

替代方案何時用它替代權衡
Appium你需要一個具備斷言與報告功能的完整 QA 框架設定繁瑣;無 MCP 整合層
Maestro基於 YAML 的 UI 測試無 MCP 整合

更多

資源

📖 閱讀 GitHub 上的官方 README

🐙 查看未解決的 issue

🔍 瀏覽全部 400+ MCP 伺服器和 Skills