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许可证。