VisionTest-移动自动化MCP服务器
一个MCP服务器，允许AI代理与Android设备和iOS模拟器进行交互——点击、滑动、键入、读取UI元素和启动应用程序。
它做什么
- 安卓+iOS 通过单个MCP服务器实现自动化
- UI交互：点击、滑动、键入文本、查找元素、阅读屏幕层次结构
- 应用管理：列出、检查和启动应用程序
- 设备检测：自动查找已连接的Android设备和已启动的iOS模拟器
- 零配置iOS：安装时使用预构建的测试包，如果需要，则回退到源代码构建
先决条件
- JDK 17或更高版本
- macOS或Linux （臂64或x86_64）
- Android平台工具 （适用于Android自动化）： 下载
- Xcode命令行工具 （仅适用于iOS模拟器自动化，macOS）
安装
快速安装（推荐）
curl -fsSL https://github.com/docer1990/visiontest/releases/latest/download/install.sh | bash这将：
- 检查是否安装了Java 17+
- 下载最新版本的JAR、Android APK和iOS测试包
- 创建一个
visiontest命令输入~/.local/bin/ - 通过SHA-256校验和验证所有下载
您可以自定义安装目录：
VISIONTEST_DIR="$HOME/my-tools/visiontest" curl -fsSL https://github.com/docer1990/visiontest/releases/latest/download/install.sh | bash要更新，请重新运行相同的命令。
配置您的AI编码工具
Claude Code
claude mcp add visiontest java -- -jar ~/.local/share/visiontest/visiontest.jarClaude Desktop
编辑配置文件：
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"visiontest": {
"command": "java",
"args": ["-jar", "/ABSOLUTE/PATH/TO/.local/share/visiontest/visiontest.jar"]
}
}
}注： 替换/ABSOLUTE/PATH/TO使用您的主目录（例如。/Users/yourname在macOS上，/home/yourname在Linux上）。JSON无法扩展~.
GitHub Copilot CLI
添加 ~/.copilot/mcp-config.json:
{
"mcpServers": {
"visiontest": {
"command": "java",
"args": ["-jar", "/ABSOLUTE/PATH/TO/.local/share/visiontest/visiontest.jar"],
"type": "stdio"
}
}
}OpenAI Codex CLI
codex mcp add visiontest -- java -jar ~/.local/share/visiontest/visiontest.jar或添加到 ~/.codex/config.toml:
[mcp_servers.visiontest]
command = "java"
args = ["-jar", "/ABSOLUTE/PATH/TO/.local/share/visiontest/visiontest.jar"]OpenCode
添加 opencode.json （项目根或 ~/.config/opencode/opencode.json):
{
"mcp": {
"visiontest": {
"type": "local",
"command": ["java", "-jar", "/ABSOLUTE/PATH/TO/.local/share/visiontest/visiontest.jar"]
}
}
}从源代码构建
有关开发或贡献，请参阅 贡献.md.
用法
您的AI编码工具通过MCP自动发现所有可用工具。只需让它与设备交互，它就会使用正确的工具。
Android工作流
1. install_automation_server → Install APKs (one-time setup)
2. start_automation_server → Start the JSON-RPC server
3. get_interactive_elements → Get interactive elements with tap coordinates
4. android_tap_by_coordinates → Tap using centerX/centerY
5. android_input_text → Type text into focused fieldiOS工作流程
1. ios_start_automation_server → Start XCUITest server (pre-built or source build)
2. ios_get_interactive_elements → Get interactive elements with tap coordinates
3. ios_tap_by_coordinates → Tap using centerX/centerY
4. ios_input_text → Type text into focused field可用工具
设备管理： available_device_android, list_apps_android, info_app_android, launch_app_android, ios_available_device, ios_list_apps, ios_info_app, ios_launch_app
安卓自动化： install_automation_server, start_automation_server, automation_server_status, get_ui_hierarchy, get_interactive_elements, find_element, android_tap_by_coordinates, android_swipe, android_swipe_direction, android_swipe_on_element, android_get_device_info, android_input_text, android_press_back, android_press_home
iOS自动化： ios_start_automation_server, ios_automation_server_status, ios_get_ui_hierarchy, ios_get_interactive_elements, ios_find_element, ios_tap_by_coordinates, ios_swipe, ios_swipe_direction, ios_get_device_info, ios_input_text, ios_press_home, ios_stop_automation_server
CLI使用情况
同样的操作也可以作为直接CLI命令使用——不需要MCP客户端：
visiontest automation_server_status -p android
visiontest get_interactive_elements -p ios
visiontest tap_by_coordinates -p android 100 200
visiontest screenshot -p ios --output ./screenshot.png
visiontest swipe_direction -p android up --distance long --speed fast每个命令都需要 --platform android 或 --platform ios （别名 -p).跑 visiontest --help 获取完整命令列表，或 visiontest --help 用于每个命令的使用。
没有争论， visiontest 启动MCP stdio服务器。
退出代码
| 代码 | 含义 |
|---|---|
| 0 | 成功 |
| 1 | 一般故障 |
| 2 | 使用错误（缺少/无效参数） |
| 3 | 无法访问自动化服务器 |
| 4 | 未找到设备/模拟器 |
| 5 | 此命令不支持平台 |
配置
环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
VISION_TEST_LOG_LEVEL | PRODUCTION | PRODUCTION, DEVELOPMENT, DEBUG |
VISION_TEST_APK_PATH | （自动检测） | Android测试APK的显式路径 |
VISION_TEST_IOS_PROJECT_PATH | （自动检测） | iOS的显式路径 .xcodeproj |
VISIONTEST_DIR | ~/.local/share/visiontest | 覆盖安装目录（必须位于 $HOME) |
港口
- 安卓：9008（需要ADB端口转发，自动设置）
- iOS：9009（无需端口转发——模拟器共享Mac的网络）
未来计划
- \[x\] 文本输入/打字支持
- \[x\] 通过UIAutomator/XCUITest捕获屏幕截图
- \[x\] CLI模式（无需MCP即可直接使用命令行）
- \[\]长压机操作
- \[\]等待/同步E2E测试操作
- \[\]多设备协调
- \[\]通用应用程序安装/卸载
- \[\]剪贴板操作（读/写）
- \[\]物理iOS设备支持
- \[\]WebSocket支持实时更新
- \[\]通知/状态栏交互
- \[\]权限对话框自动化
- \[\]自动化会话的视频录制
- \[\]单独的仅CLI工件（下载量较小，无MCP依赖关系）
贡献
看 贡献.md 用于构建源代码说明、架构详细信息、JSON-RPC API参考、测试指南以及如何扩展VisionTest。
许可证
此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。