JinDaGe - appium-mcp-claude-android MCP Details

article

README

🚀 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

设备准备

安卓真机

启用USB调试（开发者选项）
通过USB连接到计算机
允许调试
在终端中检查：adb devices

安卓模拟器

在安卓工作室中使用AVD管理器创建并运行模拟器
在终端中检查：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许可证。

appium-mcp-claude-android