MCP Appium

MCP Appium-使用模型上下文协议的自动移动测试

MCP Appium将Appium作为模型上下文协议（MCP）服务器提供，AI代理可以自动控制和测试移动设备。

主要功能

• 自动启动服务器：自动启动Appium服务器（无需GUI）
• 自动装置检测: adb devices通过自动检测连接的Android设备
• 自动设置：使用检测到的装置信息自动生成设置文件
• 灵活的测试：对设备上的所有应用进行自由测试，不受特定应用的限制
• 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

Windows（自动安装一行）：

py -m pip install mcp-appium && mcp-appium-install --install-deps -y

2.在Claude Code中打开

# 설치한 디렉토리에서
claude
# 또는 다른 방법으로 Claude Code를 해당 디렉토리에서 실행

Claude Code .mcp.json自动检测并请求MCP服务器批准。

3.使用

在Claude Code中：

"연결된 기기 확인해줘"  → list_devices
"Appium 설정하고 연결해줘"  → setup_appium_connection (자동 설정!)
"현재 화면 요소 보여줘"  → get_screen_elements

详细的安装方法包括： 安装.md请参阅。

基本要求

1.安装Node.js和Appium

# Node.js 설치 (https://nodejs.org/)

# Appium 전역 설치
npm install -g appium

# UiAutomator2 드라이버 설치
appium driver install uiautomator2

如果对全局安装感到负担（权限/冲突等），也可以进行本地安装： npm install appium 后 npx appium ...以运行。\ 这个项目 appium如果不在此PATH中 npx --no-install appium也会自动尝试。

注意：在MacOS/Linux上 ./install.sh / install-remote.sh如果没有Node.js/npm（Homebrew/apt等可用），将尝试安装。\ 如果仅使用pip安装，则MacOS/Linux mcp-appium-install --install-node --install-appium，Windows mcp-appium-install --install-deps -y可以使用自动安装。

2.安装Android SDK和ADB

• 安装Android Studio后安装SDK Platform-Tools
• 或者，下载独立的Platform-Tools：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

准备装置

Android物理设备

1. 启用USB调试（开发者选项）
2. 通过USB连接到计算机
3. 允许调试批准
4. 在终端确认： adb devices

Android模拟器

1. 在Android Studio中使用AVD Manager创建和运行模拟器
2. 在终端确认： adb devices

使用方法

参考：如果您在上面的“快速入门”中运行了安装脚本，则MCP服务器已经注册。

验证安装

# MCP 서버 목록 확인
claude mcp list

# "appium"이 목록에 있어야 합니다

默认工作流

1. 验证装置连接

   list_devices 도구 사용

1. 自动设置和连接Appium

   setup_appium_connection 도구 사용

此工具将自动执行以下操作：

- 启动Appium服务器 - 自动检测连接的装置 - 自动生成配置文件 - 连接装置

1. 检查屏幕元素

   get_screen_elements 도구 사용

1. 执行动作

   execute_action 도구로 탭, 입력, 스와이프 등 수행

1. 运行自动化方案

   run_test_scenario 도구로 자연어 시나리오 실행

MCP工具列表

1.setup_appium_connection

启动Appium服务器并自动连接到装置。

参数:

• port （可选）：Appium服务器端口（默认值：4723）

示例:

"Appium 설정하고 기기에 연결해줘"

2.设备列表

显示所有连接的Android设备列表。

示例:

"연결된 기기 목록 보여줘"

3.启动_客户端_服务器

仅手动启动Appium服务器。

参数:

• port （可选）：Appium服务器端口（默认值：4723）

4.停止appium_server

停止正在运行的Appium服务器。

5.get_screen_nelements

获取当前屏幕上的所有UI元素。

6.执行操作

在移动设备上运行特定动作。

支持动作:

• tap：元素选项卡
• input_text：输入文本
• swipe：刷
• long_press：长按
• back：后退
• hide_keyboard：隐藏键盘
• scroll_down：向下滚动
• scroll_up：向上滚动

7.运行测试场景

自动运行用自然语言编写的测试方案。

示例:

"설정 앱을 열고 Wi-Fi 메뉴로 이동해줘"
"카카오톡을 열고 검색창에 '테스트' 입력해줘"

示例使用情况

方案1：首选项和测试

User: "연결된 기기 확인해줘"
Claude: [list_devices 실행]

User: "Appium 설정하고 연결해줘"
Claude: [setup_appium_connection 실행]

User: "현재 화면에 뭐가 있는지 보여줘"
Claude: [get_screen_elements 실행]

User: "설정 아이콘 눌러줘"
Claude: [execute_action with tap 실행]

方案2：自动化测试

User: "갤러리 앱을 열고 첫 번째 사진을 선택한 다음 공유 버튼을 눌러줘"
Claude: [run_test_scenario 실행]

故障射击

“Appium not found”错误

# Appium이 설치되어 있는지 확인
appium --version

# 없다면 설치
npm install -g appium
appium driver install uiautomator2

“No devices found”错误

# ADB로 기기 연결 확인
adb devices

# 기기가 보이지 않으면:
# 1. USB 디버깅 활성화 확인
# 2. USB 케이블 재연결
# 3. 에뮬레이터 재시작

“Connection拒绝”错误

• 检查防火墙设置
• 验证端口4723是否在使用中： lsof -i :4723 （macOS/Linux）
• 使用其他端口： setup_appium_connection 呼叫时 port 指定参数

检查日志

Appium服务器日志 appium.log 存储在文件中。

许可证

MIT许可证