Appium MCP Claude Android

🚀 MCP Appium - 基於模型上下文協議的移動自動化測試

MCP Appium將Appium作為MCP（模型上下文協議）服務器提供，使AI代理能夠自動控制和測試移動設備。

✨ 主要特性

• 自動啟動服務器：自動啟動Appium服務器（無需GUI）
• 自動設備檢測：通過 adb devices 自動檢測連接的安卓設備
• 自動配置：根據檢測到的設備信息自動生成配置文件
• 靈活測試：不侷限於特定應用，可自由測試設備上的所有應用
• MCP集成：與Claude Code等AI代理完美集成
• 一鍵安裝：通過自動安裝腳本輕鬆完成安裝並註冊到MCP

📦 安裝指南

1. 安裝

方法1：克隆倉庫後安裝（推薦）

git clone https://github.com/supremehyo/appium-mcp-claude-android.git
cd appium-mcp-claude-android
./install.sh

方法2：遠程安裝（安裝到主目錄）

curl -sSL https://raw.githubusercontent.com/supremehyo/appium-mcp-claude-android/main/install-remote.sh | bash
# 安裝後：cd ~/.mcp-appium

2. 在Claude Code中打開

# 在安裝目錄下
claude
# 或者通過其他方式在該目錄下運行Claude Code

Claude Code會自動檢測 .mcp.json 並請求MCP服務器批准。

3. 使用

在Claude Code中：

"請查看已連接的設備"  → list_devices
"請配置並連接Appium"  → setup_appium_connection（自動配置！）
"請顯示當前屏幕元素"  → get_screen_elements

詳細安裝方法請參考 INSTALL.md。

🔧 技術細節

必需依賴

1. 安裝Node.js和Appium

# 安裝Node.js (https://nodejs.org/)

# 全局安裝Appium
npm install -g appium

# 安裝UiAutomator2驅動
appium driver install uiautomator2

2. 安裝安卓SDK和ADB

• 安裝安卓工作室後，安裝SDK平臺工具
• 或者下載獨立的平臺工具：https://developer.android.com/studio/releases/platform-tools

設置環境變量：

# macOS/Linux（添加到.bashrc或.zshrc）
export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/platform-tools

# Windows（添加到系統環境變量）
ANDROID_HOME=C:\Users\YourName\AppData\Local\Android\Sdk
Path=%Path%;%ANDROID_HOME%\platform-tools

3. 安裝Python包

pip install -r requirements.txt

設備準備

安卓真機

1. 啟用USB調試（開發者選項）
2. 通過USB連接到計算機
3. 允許調試
4. 在終端中檢查：adb devices

安卓模擬器

1. 在安卓工作室中使用AVD管理器創建並運行模擬器
2. 在終端中檢查：adb devices

💻 使用示例

基本用法

1. 檢查安裝情況

# 查看MCP服務器列表
claude mcp list

# 列表中應包含 "appium"

2. 基本工作流程

• 檢查設備連接

  使用 list_devices 工具
  

• 自動配置並連接Appium

  使用 setup_appium_connection 工具（自動配置！）
  

  該工具會自動執行以下操作：
  • 啟動Appium服務器
  • 自動檢測連接的設備
  • 自動生成配置文件
  • 連接設備
• 查看屏幕元素

  使用 get_screen_elements 工具
  

• 執行操作

  使用 execute_action 工具執行點擊、輸入、滑動等操作
  

• 運行自動化場景

  使用 run_test_scenario 工具運行自然語言場景
  

高級用法

MCP工具列表

• setup_appium_connection：啟動Appium服務器並自動連接到設備。 參數：
  • port（可選）：Appium服務器端口（默認值：4723） 示例：

  "請配置Appium並連接到設備"
  

• list_devices：顯示所有連接的安卓設備列表。 示例：

  "請顯示已連接的設備列表"
  

• start_appium_server：手動啟動Appium服務器。 參數：
  • port（可選）：Appium服務器端口（默認值：4723）
• stop_appium_server：停止正在運行的Appium服務器。
• get_screen_elements：獲取當前屏幕的所有UI元素。
• execute_action：在移動設備上執行特定操作。 支持的操作：
  • tap：點擊元素
  • input_text：輸入文本
  • swipe：滑動
  • long_press：長按
  • back：返回
  • hide_keyboard：隱藏鍵盤
  • scroll_down：向下滾動
  • scroll_up：向上滾動
• run_test_scenario：自動運行用自然語言編寫的測試場景。 示例：

  "打開設置應用並進入Wi-Fi菜單"
  "打開KakaoTalk並在搜索框中輸入 '測試'"
  

示例使用場景

場景1：基本設置和測試

用戶："請查看已連接的設備"
Claude：[執行 list_devices]

用戶："請配置並連接Appium"
Claude：[執行 setup_appium_connection]

用戶："請顯示當前屏幕上有什麼"
Claude：[執行 get_screen_elements]

用戶："請點擊設置圖標"
Claude：[執行帶點擊操作的 execute_action]

場景2：自動化測試

用戶："打開圖庫應用，選擇第一張照片，然後點擊分享按鈕"
Claude：[執行 run_test_scenario]

🚧 故障排除

"未找到Appium"錯誤

# 檢查Appium是否已安裝
appium --version

# 如果未安裝，則進行安裝
npm install -g appium
appium driver install uiautomator2

"未找到設備"錯誤

# 使用ADB檢查設備連接
adb devices

# 如果設備未顯示：
# 1. 檢查是否啟用了USB調試
# 2. 重新連接USB電纜
# 3. 重啟模擬器

"連接被拒絕"錯誤

• 檢查防火牆設置
• 檢查端口4723是否被佔用：lsof -i :4723（macOS/Linux）
• 使用其他端口：在調用 setup_appium_connection 時指定 port 參數

📄 日誌查看

Appium服務器日誌存儲在 appium.log 文件中。

📄 許可證

本項目採用MIT許可證。