Mobile MCP Ai

🚀 Mobile MCP AI

移動端自動化 MCP Server，為 Cursor AI 賦予移動設備控制能力，全面支持 Android 與 iOS 系統。

🚀 快速開始

1. 配置 Cursor MCP

編輯 ~/.cursor/mcp.json（macOS/Linux）或 %APPDATA%\Cursor\mcp.json（Windows）：

{
  "mcpServers": {
    "mobile-automation": {
      "command": "python",
      "args": ["-m", "mobile_mcp.mcp.mcp_server"],
      "cwd": "/path/to/your/project"
    }
  }
}

💡 模式切換（可選）：

• 默認完整版（39工具）：包含測試腳本生成、操作歷史、動態配置等 ⭐ 推薦
• 簡化版（32工具）：添加 "env": {"MOBILE_MCP_MODE": "simple"}
  • ⚠️ 簡化版不支持測試腳本生成（mobile_generate_test_script）
  • 適合只需要基礎操作的場景

📝 配置說明：

• "cwd": 項目根目錄，測試腳本會保存到此目錄的 tests/ 下
• AI功能：Cursor 會自動使用內置 AI，無需額外配置
• 其他 AI 平臺：需要時參考 配置指南

2. 連接設備

# Android 設備
adb devices  # 確認設備可見

# iOS 設備（可選）
pip install mobile-mcp-ai[ios]

3. 重啟 Cursor

配置完成後，完全退出並重新啟動 Cursor。

4. 開始使用

方式1：基礎工具（明確指定元素）

@MCP 幫我測試登錄：
1. 列出所有元素
2. 點擊 resource-id 為 "com.app:id/login_btn"
3. 在 resource-id "com.app:id/username" 輸入 "admin"
4. 截圖保存

方式2：讓 Cursor AI 分析截圖（推薦）

@MCP 幫我測試登錄：
1. 先截圖看看當前頁面
2. 分析後點擊"登錄"按鈕
3. 在"用戶名"輸入框輸入 "admin"
4. 截圖確認

Cursor AI 會自動截圖、分析圖片、找到元素座標並操作！

✨ 主要特性

🎯 AI 功能可選化

• 基礎模式：無需配置 AI 密鑰，Cursor AI 提供所有智能能力。
• 智能模式：可選擇配置 AI 密鑰，適用於構建自動化測試平臺。
• 零成本起步：基礎工具完全免費，無需額外 AI API 費用。
• 靈活選擇：可根據使用場景自由決定是否啟用 AI 功能。

📦 工具特性

• 39個工具：覆蓋元素操作、設備管理、測試生成等多個方面。
• 操作錄製：自動記錄操作過程，一鍵生成 pytest 測試腳本。
• 雙平臺支持：Android 和 iOS 採用統一接口。
• 智能驗證：按鍵操作自動驗證是否生效。

🤖 與 Cursor AI 深度集成

• MCP 協議：基於 Model Context Protocol，實現無縫集成。
• 39 個工具：提供豐富的移動端操作工具（完整版）。
• 視覺識別：Cursor AI 可直接分析截圖並進行操作。
• 測試生成：AI 操作後可一鍵生成 pytest 腳本。

📦 安裝指南

基礎安裝（推薦，Cursor 用戶首選）

# 只包含核心依賴，Cursor AI 提供所有智能能力
pip install mobile-mcp-ai

✅ 適用場景：

• 在 Cursor 中使用（最常見）。
• 使用 32 個基礎工具即可。
• 不需要額外的 AI API 密鑰。

完整安裝（構建自動化平臺）

# 額外安裝 AI SDK：通義千問、OpenAI、Claude
pip install mobile-mcp-ai[ai]

✅ 適用場景：

• 構建獨立的自動化測試平臺。
• 在 CI/CD 中使用智能工具。
• 需要脫離 Cursor 獨立運行。

💡 區別說明：基礎版不包含 dashscope、openai、anthropic 等 AI SDK，在 Cursor 中使用時完全夠用（Cursor AI 提供智能能力）。只有需要在獨立環境中運行智能工具時，才需要完整安裝。

升級到最新版本

⚠️ 重要：如果你已經安裝了舊版本，強烈建議升級到 v2.1.0！

# 升級到最新版本
pip install --upgrade mobile-mcp-ai

# 驗證版本
pip show mobile-mcp-ai

💻 使用示例

基礎用法

場景1：基礎工具測試（明確元素）

@MCP 執行以下操作：
1. 啟動應用 com.example.app
2. 列出所有可點擊元素
3. 點擊 resource-id "com.example:id/login_btn"
4. 等待元素 "com.example:id/home" 出現
5. 截圖保存

場景2：Cursor AI 視覺分析（智能推薦）

@MCP 幫我測試登錄功能：
1. 截圖看看當前頁面
2. 找到並點擊"登錄"按鈕
3. 再截圖，找到"用戶名"輸入框並輸入 "test123"
4. 找到"密碼"輸入框並輸入 "pass123"
5. 點擊"確定"按鈕
6. 截圖確認結果

高級用法

場景3：智能工具（需要配置 AI）

@MCP 檢查 AI 功能狀態
@MCP 用智能方式點擊"登錄"按鈕
@MCP 在"用戶名"輸入框輸入 "test123"

場景4：生成測試腳本（推薦）✨ 新增

@MCP 幫我測試登錄功能：
1. 啟動應用 com.example.app
2. 截圖，找到"登錄"按鈕並點擊
3. 在"用戶名"輸入 "test123"
4. 在"密碼"輸入 "pass123"
5. 點擊"提交"按鈕

@MCP 生成剛才操作的測試腳本

AI 會自動生成一個完整的 pytest 測試腳本：

• ✅ 保存到你的項目 tests/ 目錄。
• ✅ 包含智能等待邏輯（頁面加載、跳轉、輸入）。
• ✅ 自動處理彈窗（存在則點擊，不存在跳過）。
• ✅ 支持多設備（自動檢測設備ID）。
• ✅ 獨立運行（只需要 pip install uiautomator2 pytest）。

生成的腳本示例：

def test_登錄(device):
    d = device
    
    # 步驟1: 點擊"登錄"
    d.click(540, 338)
    time.sleep(2.0)  # 智能等待頁面跳轉
    
    # 步驟2: 輸入用戶名
    d(resourceId="com.example:id/username").set_text("test123")
    time.sleep(1.5)
    
    # 步驟3: 點擊提交
    d.click(972, 1200)
    time.sleep(2.0)
    
    assert d(text="首頁").exists()

🛠️ 工具列表概覽

📊 工具分類統計

🔥 常用工具速覽

基礎操作（不需要 AI）

• mobile_list_elements - 列出所有可交互元素
• mobile_click_by_id / mobile_click_by_text - 精確點擊
• mobile_input_text_by_id - 輸入文本
• mobile_take_screenshot - 截圖（供 Cursor AI 分析）
• mobile_wait - 等待指定時間或元素 ⭐ 完整版獨有
• mobile_wait_for_element - 等待元素出現

智能操作（需要 AI，可選）

• mobile_smart_click - 自然語言智能點擊
• mobile_smart_input - 自然語言智能輸入
• mobile_analyze_screenshot - AI 視覺分析
• mobile_execute_test_case - 智能執行測試 ⭐ 完整版獨有
• mobile_generate_test_script - 生成 pytest 腳本 ⭐ 完整版獨有

設備與應用管理

• mobile_list_devices - 列出連接的設備
• mobile_launch_app - 啟動應用
• mobile_list_apps - 列出已安裝應用
• mobile_get_screen_size - 獲取屏幕尺寸

動態配置 ⭐ 完整版獨有

• mobile_configure - 調整等待時間、驗證策略等
• mobile_get_config - 查看當前配置

📋 新增工具：設備連接管理（check_connection, reconnect_device）、操作歷史管理（get_operation_history, clear_operation_history）

🎯 智能驗證功能詳解

mobile_press_key - 徹底解決"假成功"問題

問題背景： 傳統按鍵操作只檢查命令是否執行，不驗證按鍵是否真的生效，導致：

• ✗ 命令執行成功 ≠ 按鍵生效
• ✗ 測試顯示通過，實際操作失敗
• ✗ 搜索鍵在某些應用/輸入法中不起作用

智能驗證方案：

# 方式1: 驗證模式（推薦，默認）
await press_key("search", verify=True)
# ✅ 自動檢測頁面變化
# ✅ 搜索鍵無效時自動嘗試回車鍵
# ✅ 返回真實操作結果

# 方式2: 快速模式
await press_key("back", verify=False)
# ⚡ 執行後立即返回
# ⚠️  不保證按鍵效果

工作原理：

1. 操作前快照 - 記錄當前頁面狀態。
2. 執行按鍵 - 發送按鍵命令。
3. 頁面監測 - 等待並檢測頁面變化（最多2秒）。
4. 智能判斷 - 頁面變化 > 5% 認為成功。
5. 搜索鍵回退 - SEARCH 無效時自動嘗試 ENTER。

使用示例：

@MCP 幫我搜索：
1. 在搜索框輸入 "測試內容"
2. 按搜索鍵（自動驗證）

返回結果：

{
  "success": true,
  "key": "search",
  "keycode": 84,
  "verified": true,
  "page_changed": true,
  "fallback_used": false,
  "message": "搜索鍵(SEARCH)生效"
}

如果 SEARCH 鍵無效：

{
  "success": true,
  "key": "search",
  "keycode": 66,
  "verified": true,
  "page_changed": true,
  "fallback_used": true,
  "message": "搜索鍵(SEARCH)無效，已使用ENTER鍵替代併成功"
}

如果按鍵無效：

{
  "success": false,
  "key": "search",
  "verified": true,
  "page_changed": false,
  "message": "按鍵命令執行成功但頁面未變化，可能按鍵未生效"
}

使用建議：

性能對比：

• 快速模式：~0.05秒（不保證效果）。
• 驗證模式：~0.5 - 2秒（確保成功）。
• 額外耗時：小於2秒，換來可靠性。

支持的按鍵：

• enter / 回車 - Enter鍵 (keycode=66)
• search / 搜索 - 搜索鍵 (keycode=84, 自動回退到66)
• back / 返回 - 返回鍵 (keycode=4)
• home - Home鍵 (keycode=3)
• 直接使用keycode數字（如 66）

演示腳本： 運行 python backend/mobile_mcp/examples/press_key_verification_demo.py 查看完整演示。

📚 詳細文檔

• 用戶配置指南 - AI 密鑰配置、常見問題。
• 啟動指南 - 完整的安裝和配置步驟。
• 測試腳本生成 - 如何生成 pytest 測試腳本。
• 自動化行為配置說明 - 控制屏幕方向和自動關閉廣告。

🔧 技術細節

• MCP 協議：與 Cursor AI 無縫集成。
• UIAutomator2：Android 自動化引擎。
• Appium：iOS 自動化支持（可選）。
• 多 AI 支持：通義千問、OpenAI、Claude（可選）。

📄 許可證

本項目採用 Apache License 2.0 許可協議。