mobile-mcp-ai 2.0.1

移动端自动化 MCP Server - 支持 Android/iOS，AI 功能可选（基础工具不需要 AI）

Mobile MCP AI

移动端自动化 MCP Server - 为 Cursor AI 提供移动设备控制能力，支持 Android/iOS

⭐ 如果这个项目对你有帮助，请给个 Star 支持一下！⭐

🆕 v2.0.0 重大更新：AI 功能可选化！基础工具不需要配置 AI 密钥

✨ v2.0.0 核心特性

🎯 AI 功能可选化（重大更新）

• 基础模式：不需要配置 AI 密钥，Cursor AI 提供所有智能能力
• 智能模式：可选配置 AI 密钥，适合构建自动化测试平台
• 零成本起步：基础工具完全免费，无需额外 AI API 费用
• 灵活选择：根据使用场景自由选择是否启用 AI 功能

📦 双层工具架构

基础工具（9个，不需要 AI）

• mobile_list_elements - 列出所有可交互元素
• mobile_click_by_id - 通过 resource-id 精确点击
• mobile_click_by_text - 通过文本内容点击
• mobile_click_at_coords - 点击指定坐标
• mobile_input_text_by_id - 在输入框输入文本
• mobile_find_elements_by_class - 按类名查找元素
• mobile_wait_for_element - 等待元素出现
• mobile_take_screenshot - 截取屏幕（支持 Cursor AI 视觉识别）
• mobile_take_screenshot_region - 区域截图

智能工具（4个，需要 AI，可选）

• mobile_smart_click - 自然语言智能点击
• mobile_smart_input - 自然语言智能输入
• mobile_analyze_screenshot - AI 视觉识别定位
• mobile_get_ai_status - 检查 AI 功能状态

通用工具（4个）

• mobile_snapshot - 获取页面结构
• mobile_launch_app - 启动应用
• mobile_swipe - 滑动屏幕
• mobile_press_key - 按键操作

🌐 跨平台支持

• 双平台支持：完美支持 Android 和 iOS
• 统一接口：通过适配器模式实现代码复用
• 设备管理：自动检测和管理连接的设备

🤖 与 Cursor AI 深度集成

• MCP 协议：基于 Model Context Protocol，无缝集成
• 17 个工具：丰富的移动端操作工具
• 视觉识别：Cursor AI 可以直接分析截图并操作

📦 安装

基础安装（推荐）

# 不需要 AI 密钥，完全免费
pip install mobile-mcp-ai

完整安装（可选）

# 如果需要智能工具或构建自动化平台
pip install mobile-mcp-ai[ai]

🚀 快速开始

1. 配置 Cursor MCP

编辑 ~/.cursor/mcp.json（macOS/Linux）或 %APPDATA%\Cursor\mcp.json（Windows）：

基础模式（推荐，默认使用 Cursor AI，完全免费）：

{
  "mcpServers": {
    "mobile-automation": {
      "command": "python",
      "args": ["-m", "mobile_mcp.mcp.mcp_server_simple"],
      "env": {}
    }
  }
}

🎯 默认行为：

• ✅ 在 Cursor 中运行时，自动使用 Cursor AI（免费，无需配置）
• ✅ 智能定位、视觉识别等 AI 功能开箱即用
• ✅ 不会消耗你的 API 额度，完全零成本

智能模式（可选，使用其他 AI 平台）：

{
  "mcpServers": {
    "mobile-automation": {
      "command": "python",
      "args": ["-m", "mobile_mcp.mcp.mcp_server_simple"],
      "env": {
        "AI_PROVIDER": "qwen",
        "QWEN_API_KEY": "sk-your-api-key"
      }
    }
  }
}

💡 提示：只有在以下情况才需要配置 AI 密钥：

• 想使用通义千问、Claude、OpenAI 等其他 AI 平台
• 构建独立的自动化测试平台（非 Cursor 环境）
• 需要离线运行或集成到 CI/CD

详细配置说明：用户配置指南

2. 连接设备

# Android 设备
adb devices  # 确认设备可见

# iOS 设备（可选）
pip install mobile-mcp-ai[ios]

3. 重启 Cursor

配置完成后，完全退出并重新启动 Cursor。

4. 开始使用

方式1：基础工具（明确指定元素）

@MCP 帮我测试登录：
1. 列出所有元素
2. 点击 resource-id 为 "com.app:id/login_btn"
3. 在 resource-id "com.app:id/username" 输入 "admin"
4. 截图保存

方式2：让 Cursor AI 分析截图（推荐）

@MCP 帮我测试登录：
1. 先截图看看当前页面
2. 分析后点击"登录"按钮
3. 在"用户名"输入框输入 "admin"
4. 截图确认

Cursor AI 会自动截图、分析图片、找到元素坐标并操作！

💡 使用示例

场景1：基础工具测试（明确元素）

@MCP 执行以下操作：
1. 启动应用 com.example.app
2. 列出所有可点击元素
3. 点击 resource-id "com.example:id/login_btn"
4. 等待元素 "com.example:id/home" 出现
5. 截图保存

场景2：Cursor AI 视觉分析（智能推荐）

@MCP 帮我测试登录功能：
1. 截图看看当前页面
2. 找到并点击"登录"按钮
3. 再截图，找到"用户名"输入框并输入 "test123"
4. 找到"密码"输入框并输入 "pass123"
5. 点击"确定"按钮
6. 截图确认结果

场景3：智能工具（需要配置 AI）

@MCP 检查 AI 功能状态
@MCP 用智能方式点击"登录"按钮
@MCP 在"用户名"输入框输入 "test123"

🛠️ 工具列表

基础工具（不需要 AI，共 9 个）

工具	说明	示例
mobile_list_elements	列出所有可交互元素	显示 resource_id, text, bounds
mobile_click_by_id	通过 resource-id 点击	精确可靠
mobile_click_by_text	通过文本点击	文本完全匹配
mobile_click_at_coords	点击坐标	配合截图分析使用
mobile_input_text_by_id	输入文本	通过 resource-id
mobile_find_elements_by_class	按类名查找	如 EditText
mobile_wait_for_element	等待元素出现	等待页面加载
mobile_take_screenshot	截屏	供 Cursor AI 视觉识别
mobile_take_screenshot_region	区域截屏	局部分析

智能工具（需要 AI，可选，共 4 个）

工具	说明	使用场景
mobile_smart_click	自然语言点击	平台自动化
mobile_smart_input	自然语言输入	批量测试
mobile_analyze_screenshot	AI 分析截图	复杂场景
mobile_get_ai_status	检查 AI 状态	调试配置

通用工具（共 4 个）

工具	说明
mobile_snapshot	获取页面结构
mobile_launch_app	启动应用
mobile_swipe	滑动屏幕
mobile_press_key	按键操作

总计：17 个工具

📚 文档

• 用户配置指南 - AI 密钥配置、常见问题
• 启动指南 - 完整的安装和配置步骤
• 测试脚本生成 - 如何生成 pytest 测试脚本

🎯 使用场景选择

个人使用 Cursor（推荐新手）

• 只装基础版：pip install mobile-mcp-ai
• 不配置 AI key
• 通过 Cursor AI 使用（Cursor AI 自带视觉识别）
• 💰 完全免费

平台开发（推荐开发者）

• 装完整版：pip install mobile-mcp-ai[ai]
• 配置 AI key
• 可以脱离 Cursor 独立使用
• 适合做自动化测试平台、CI/CD 集成
• 💸 需要 AI API 费用

🆕 v2.0.0 更新日志

重大改进

• ✨ AI 功能可选化：基础工具不需要 AI 密钥
• 🚀 新增 3 个工具：截图、区域截图、AI 视觉识别
• 📦 依赖优化：核心依赖最小化
• 🏗️ 架构重构：分离基础工具和智能工具
• 🐛 修复 AI 响应解析问题
• 📝 完善用户文档

向后兼容

• ✅ 完全兼容之前的使用方式
• ✅ 已配置 AI 的用户无需修改
• ✅ 新用户可以选择不配置 AI

📊 技术栈

• MCP 协议：与 Cursor AI 无缝集成
• UIAutomator2：Android 自动化引擎
• Appium：iOS 自动化支持（可选）
• 多 AI 支持：通义千问、OpenAI、Claude（可选）

🤝 贡献

欢迎提交 Issue 和 Pull Request！

有问题或建议？欢迎在 Issues 中反馈。

📄 License

Apache License 2.0

---

⭐ 如果这个项目对你有帮助，请给个 Star 支持一下！⭐

Gitee 仓库 | GitHub 仓库 | PyPI 发布

让移动端测试更简单！ 🚀