iOS_SETUP_GUIDE.md

iOS 自动化配置指南

本文档详细介绍如何配置 Mobile MCP 支持 iOS 设备自动化。

📋 环境要求

要求	说明
操作系统	macOS（必须，Windows/Linux 不支持）
Xcode	15.0+ （建议 16.0+，支持最新 iOS）
Apple ID	免费账号即可（限制安装 3 个 App）
iOS 设备	iPhone/iPad，通过 USB 数据线连接
Python	3.9 或更高版本
Homebrew	用于安装 libimobiledevice

🚀 快速开始

第一步：安装依赖

# 安装 tidevice 和 facebook-wda
pip3 install tidevice facebook-wda

# 安装 libimobiledevice（用于 iproxy）
brew install libimobiledevice

第二步：连接 iOS 设备

1. 用 USB 数据线连接 iPhone 到 Mac
2. iPhone 上点击"信任此电脑"
3. 验证连接：

tidevice list

应该看到类似输出：

UDID                       SerialNumber    NAME            MarketName      ProductVersion  ConnType
00008110-000C31D426D9801E  XXXXXX          我的iPhone      iPhone 13       18.5            USB

🔧 WebDriverAgent 编译安装

WebDriverAgent (WDA) 是 iOS 自动化的核心组件，需要用 Xcode 编译安装到设备上。

步骤 1：克隆 WebDriverAgent 项目

git clone https://github.com/appium/WebDriverAgent.git
cd WebDriverAgent
open WebDriverAgent.xcodeproj

步骤 2：配置签名

在 Xcode 中：

1. 左侧选择 WebDriverAgent 项目（蓝色图标）
2. 中间 TARGETS 选择 WebDriverAgentRunner
3. 点击 Signing & Capabilities 标签
4. ✅ 勾选 Automatically manage signing
5. Team 选择你的 Apple ID
6. Bundle Identifier 改成唯一的，例如：

   com.facebook.WebDriverAgentRunner.你的名字
   

⚠️ Bundle Identifier 必须唯一，建议加上你的名字或公司名

步骤 3：配置 IntegrationApp（可选但推荐）

重复上面的签名配置，选择 IntegrationApp target。

步骤 4：选择设备并编译

1. Xcode 顶部 Scheme 选择器 → 选择 WebDriverAgentRunner
2. 设备选择器 → 选择你的 iPhone
3. 按 ⌘ + U（或菜单 Product → Test）

步骤 5：信任开发者（首次安装）

首次安装会提示"不受信任的开发者"，需要在 iPhone 上操作：

设置 → 通用 → VPN与设备管理 → 点击你的开发者账号 → 信任

然后回到 Xcode 再按一次 ⌘ + U

步骤 6：验证安装成功

Xcode 控制台会显示类似：

ServerURLHere->http://192.168.x.x:8100<-ServerURLHere

🌐 端口转发

WDA 在设备上运行后，需要通过 iproxy 将端口转发到本地：

iproxy 8100 8100

验证连接：

curl http://localhost:8100/status

成功响应：

{
  "value": {
    "message": "WebDriverAgent is ready to accept commands",
    "state": "success",
    "ready": true
  }
}

⚙️ 配置 Mobile MCP

方式 1：pip 安装后配置（推荐）

先安装：pip install mobile-mcp-ai

然后编辑 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "mobile-automation": {
      "command": "mobile-mcp"
    }
  }
}

💡 提示：pip 安装后会自动检测设备类型（iOS/Android），无需手动配置平台

方式 2：源码方式配置

编辑 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "mobile-automation": {
      "command": "/path/to/your/venv/bin/python",
      "args": ["-m", "mobile_mcp.mcp_tools.mcp_server"],
      "cwd": "/path/to/mobile_mcp",
      "env": {
        "MOBILE_PLATFORM": "ios"
      }
    }
  }
}

⚠️ 请将 /path/to/ 替换为你的实际路径

方式 3：.env 文件（仅源码开发）

在项目根目录创建 .env 文件：

# 平台配置
MOBILE_PLATFORM=ios

# 设备 ID（auto=自动选择）
MOBILE_DEVICE_ID=auto

# 日志级别
LOG_LEVEL=INFO

配置说明

环境变量	说明	默认值
MOBILE_PLATFORM	平台类型 (ios 或 android)	自动检测
MOBILE_DEVICE_ID	设备 ID，auto 自动选择	auto
LOG_LEVEL	日志级别	INFO

🔄 每次使用流程

启动 WDA

每次重启电脑或断开 iPhone 后，需要重新启动 WDA：

方式 1：Xcode（推荐）

1. 打开 WebDriverAgent.xcodeproj
2. 选择 WebDriverAgentRunner scheme
3. 选择你的 iPhone
4. 按 ⌘ + U

方式 2：tidevice（可能不支持新版 iOS）

tidevice wdaproxy -B com.facebook.WebDriverAgentRunner.你的名字.xctrunner

端口转发

iproxy 8100 8100

验证连接

curl http://localhost:8100/status

📱 可用的 MCP 工具

工具	功能
mobile_check_connection	检查设备连接状态
mobile_take_screenshot	截图
mobile_get_screen_size	获取屏幕尺寸
mobile_list_elements	列出页面元素
mobile_click_by_text	通过文字点击
mobile_click_by_id	通过 ID 点击
mobile_click_at_coords	通过坐标点击
mobile_swipe	滑动屏幕
mobile_input_text_by_id	输入文字
mobile_launch_app	启动应用
mobile_terminate_app	关闭应用
mobile_press_key	按键（home/back）
mobile_wait	等待指定时间

❗ 常见问题

Q1: curl: (7) Failed to connect to localhost port 8100

原因：WDA 服务未启动

解决：

1. 在 Xcode 中按 ⌘ + U 启动 WDA
2. 运行 iproxy 8100 8100

Q2: 免费开发者账号 App 数量限制

错误：This device has reached the maximum number of installed apps using a free developer profile

原因：免费账号最多安装 3 个开发者 App

解决：

# 查看已安装的开发者 App
tidevice applist | grep -i wda

# 卸载不需要的 App
tidevice uninstall com.xxx.xxx

Q3: tidevice 不支持新版 iOS

错误：InvalidService 或下载 DeviceSupport 失败

原因：tidevice 对 iOS 18+ 支持有限

解决：使用 Xcode 直接启动 WDA（⌘ + U），然后用 iproxy 转发端口

Q4: 不受信任的开发者

解决：iPhone 上进入 设置 → 通用 → VPN与设备管理 → 信任开发者账号

Q5: Bundle Identifier 冲突

解决：修改 Bundle Identifier 为唯一值，如 com.facebook.WebDriverAgentRunner.你的名字

🔀 切换平台

切换到 iOS

编辑 ~/.cursor/mcp.json：

"env": {
  "MOBILE_PLATFORM": "ios"
}

切换到 Android

编辑 ~/.cursor/mcp.json：

"env": {
  "MOBILE_PLATFORM": "android"
}

⚠️ 修改配置后需要重启 Cursor 生效

💡 提示：如果使用 pip 安装方式（command: "mobile-mcp"），会自动检测设备类型，无需手动配置

✅ 快速检查清单

配置完成后，确保以下所有项目都已完成：

• macOS 系统
• 已安装 Xcode
• 已安装 tidevice 和 facebook-wda
• 已安装 libimobiledevice（iproxy）
• iPhone 通过 USB 连接且已信任电脑
• WebDriverAgent 已编译安装到 iPhone
• 已在 iPhone 上信任开发者证书
• WDA 服务已启动（Xcode ⌘+U）
• iproxy 端口转发已运行
• curl http://localhost:8100/status 返回成功
• MCP 配置已正确设置（pip 安装自动检测，或源码设置 MOBILE_PLATFORM=ios）
• 已重启 Cursor 使配置生效

🎯 完整流程总结

┌─────────────────────────────────────────────────────────┐
│                    首次配置（一次性）                      │
├─────────────────────────────────────────────────────────┤
│  1. 安装依赖：pip install mobile-mcp-ai                 │
│  2. 安装 iOS 工具：pip install tidevice facebook-wda    │
│  3. 安装 iproxy：brew install libimobiledevice          │
│  4. 克隆 WebDriverAgent 项目                            │
│  5. Xcode 配置签名 → 编译安装到 iPhone（⌘+U）            │
│  6. iPhone 信任开发者证书                                │
│  7. 配置 Cursor MCP（会自动检测 iOS 设备）               │
└─────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────┐
│                    每次使用                              │
├─────────────────────────────────────────────────────────┤
│  1. USB 连接 iPhone                                     │
│  2. Xcode 启动 WDA（⌘+U）                               │
│  3. 终端运行：iproxy 8100 8100                          │
│  4. 验证：curl http://localhost:8100/status             │
│  5. 开始使用 Mobile MCP 自动化！                         │
└─────────────────────────────────────────────────────────┘

📚 参考资料

• WebDriverAgent GitHub
• tidevice GitHub
• facebook-wda GitHub
• Appium WDA 文档

---

最后更新：2025年12月