iPhone MCP

English · 简体中文

运行在电脑上的 MCP 服务，通过 Wi-Fi（默认）或 USB、CoreDevice 隧道和 RemoteXPC 开发者服务直接控制 iPhone。手机无需安装或后台运行 Actell，无需手机端 MCP、VPN、ESP32 或 WebDriverAgent。

当前面向 macOS、iOS 27+、Wi-Fi／USB、正向竖屏触控。已在拔掉 USB 后验证截图、点击、滑动、中文输入、Bonjour 发现及 TCP 中断后重连；长期稳定性仍待验收。不把协议请求成功视为界面操作成功。

安装

需要 uv、Python 3.13。uv sync 会按需安装 Python 并创建隔离环境。

git clone https://github.com/the-eric-kwok/iphone-mcp.git
cd iphone-mcp
uv sync --frozen
uv run --frozen iphone-mcp --help
uv run --frozen iphone-mcp devices

手机准备：

1. 用数据线连接 Mac，解锁手机，在 Finder 或 Xcode 中完成信任配对。

2. 在手机设置中启用开发者模式。

3. 让匹配版本的 Xcode 完成设备准备，挂载 Personalized Developer Disk Image（DDI）。本项目不下载、挂载 DDI，不更改开发者模式或信任关系。

4. 手机和 Mac 连接同一局域网，开启系统无线连接，然后拔掉数据线。关闭其他正在控制同一手机的任务，保持手机可操作。

# 首次准备：先通过 USB 完成信任，再显式开启系统无线连接。
uv run --frozen iphone-mcp devices --transport usb
uv run --frozen iphone-mcp prepare-wifi --udid <UDID>

# 拔掉数据线后验证 Wi-Fi。doctor 只连接和截图，随后释放，不发送输入或保存截图。
uv run --frozen iphone-mcp devices --transport wifi --udid <UDID>
uv run --frozen iphone-mcp doctor --udid <UDID> --transport wifi

# Bonjour 不可用时，可直接指定手机 IP。
uv run --frozen iphone-mcp doctor --udid <UDID> --host <手机IP>

prepare-wifi 只通过 USB 为指定的已配对设备设置系统 EnableWifiConnections，并读取确认；普通发现和连接不会自动修改此设置。准备完成后，手机仅运行系统服务，无需常驻 App。系统更新、重启或 DDI 状态变化后，可能需要重新在 Xcode 中准备开发者服务。

无线发现使用 macOS 系统 Bonjour，仅返回电脑已有身份能够认证的设备。macOS 的系统配对记录不能直接枚举时，传入已知 --udid 可以让系统查询对应记录，连接不依赖数据线。发现为空也需检查本地网络权限、Bonjour、局域网隔离和手机解锁状态。指定 --host 可跳过服务发现；.local 名称仍由系统 Bonjour 解析，连接始终校验所选 UDID 和配对身份。为避免误选插线虚拟网络，Wi-Fi 模式过滤链路本地、回环及组播地址，要求可用的局域网 IPv4 或非链路本地 IPv6 地址。

Wi-Fi 是默认连接方式；USB 必须显式传入 --transport usb。Wi-Fi 失败会报错，不自动回退 USB。

Related MCP server: open_phone

MCP 接入

使用 stdio，MCP 客户端负责启动进程，不需要手动常驻运行另一个 HTTP 服务。

{
  "mcpServers": {
    "iphone": {
      "command": "/opt/homebrew/bin/uv",
      "args": [
        "--directory", "/absolute/path/to/iphone-mcp",
        "run", "--frozen", "iphone-mcp", "serve"
      ]
    }
  }
}

配置模板见 examples/mcp.json。请替换 uv 和项目的绝对路径；/absolute/path/to/iphone-mcp 是占位路径。项目安装过程不会自动修改任何 MCP 客户端配置。

工具

list_devices() 每次调用刷新两种连接；list_devices(transport="wifi") 或 list_devices(transport="usb") 可单独查询，udid 可缩小范围。同一设备有两种可用路线时保留两条记录，使用 UDID 关联，避免掩盖实际连接方式。发现只读取设备身份，不启动控制会话；当前控制会话通过 device_status 查询。

例如：connect_device(udid="…", transport="wifi", host="192.168.1.20")；省略 host 时通过 Bonjour 寻找设备。状态中的 transport 和 host 表示实际选用的连接。

推荐顺序：list_devices → connect_device → screenshot → tap／drag／type_text → screenshot。

坐标属于返回图片，不是原始屏幕尺寸。默认截图最长边为 1600 像素，可以用 max_size 调整。输入必须携带最近的 frame_id；新截图、输入、停止、断线或超过 60 秒都会使旧引用失效。方向变化会拒绝坐标输入，首版不猜测横屏映射。截图引用用于绑定坐标，不能保证屏幕内容在两次调用之间未改变。

type_text 会替换手机剪贴板，不读取或保存原剪贴板，不自动回车；系统粘贴确认需要用户处理。返回 dispatched 只说明协议发送完成，必须重新截图确认实际效果。

架构

MCP 客户端
  └─ stdio MCP 服务
      └─ Controller：串行操作、截图引用、取消与不重放
          └─ CoreDeviceBackend
              ├─ Wi-Fi TCP Lockdown／USB Lockdown 配对身份
              ├─ DesktopTunnel：CoreDeviceProxy、进程内隧道、RSD
              ├─ ScreenCaptureService：按需获取 PNG，再压缩为 JPEG
              ├─ DisplayService：输入所需媒体会话、UDP 接收、RTCP 反馈
              ├─ UniversalHID／Indigo：触控、Home、粘贴按键
              └─ AppService／PasteboardService

常驻复用隧道和服务连接，输入第一次调用时才启动媒体通道。截图使用独立截图服务，不实现视频解码或返回旧视频缓存；这有利于首版验证和降低空闲解码开销，截图吞吐与延迟尚需真机测量。

每个 MCP 进程只连接一台设备，这是上游进程内网络栈的限制。同一设备的不同进程通过文件锁互斥；切换设备、连接方式或主机须先断开。锁不会约束 Xcode、Actell 或其他外部控制器。

停止只处理自己的触控、按键和媒体标识，不调用全局 stopAll。操作失败或超时时关闭当前会话，不自动重连并重放动作。输入已经发出但结果不明时，需要用户或 Agent 在新会话截图核对。物理断线时无法保证设备收到释放报告；本地清理与设备端实际释放须区分。

服务不监听 TCP 端口，不存储截图、输入文本或配对记录；依赖库使用电脑已有的配对身份。stdout 只承载 MCP，诊断写入 stderr。具备此 stdio 连接权限的客户端可以调用所有工具，没有额外逐次确认层。

验证

uv run --frozen ruff check .
uv run --frozen pytest -q
uv build

测试覆盖系统 Bonjour 的 TXT 解析与取消清理、无线身份匹配、禁止隐式 USB 回退、取消期间资源释放、无线断线唤醒、连接复用、坐标缩放、截图失效、方向变化、并发输入、取消、停止、未知结果不重放、按键释放、媒体定向停止、设备锁，以及真实子进程的 MCP 初始化、工具发现、参数校验和退出。

真机验收步骤见 docs/ACCEPTANCE.md。尚待验证持续媒体反馈、方向边界、输入期间的断线、实际关闭无线网络及设备端释放边界。Windows、Linux、横屏触控、自动 DDI 准备和视频流截图不在首版支持范围内。

代码与来源

采用 GPL-3.0-only，第三方来源见 THIRD_PARTY.md。协议能力依赖非公开开发者服务及匹配的 DDI，固定依赖版本与 uv.lock 一同维护。升级系统或依赖后应重新验收。