指南
有这么一个 MCP 服务器,能驱动一台实体 iPhone
用模型上下文协议(MCP)做东西的人,常常希望 Agent 能像用文件系统、用浏览器那样,去用一台真实的 iPhone。Manina AI CLI 就是干这个的:它在你电脑上跑一个 MCP 服务器,通过一块插在 iPhone 上的 ESP32-S3 板子跟手机打交道。Agent 要一张截图,想过之后发回点按、滑动和输入的文字。手机不用越狱,日常使用也不需要开发者账号。
这一页写给想弄清工具长什么样、链路怎么走、边界在哪的开发者。
安装并注册服务器
CLI 从 npm 来:
npx -y esp32agentMCP 服务器由同一个包通过 mcp 子命令启动。把这个命令注册到你的 MCP 客户端。用 Claude Code 的话,命令是:
claude mcp add esp32agent -- esp32agent mcp其他支持 MCP 的 Agent 照同样的形状配:可执行文件 esp32agent,参数 mcp。客户端指向这条命令即可。
Agent 能做什么
服务器给 Agent 的循环,跟人用手机的顺序一样:
- 要一张当前 iPhone 屏幕的截图。
- 看着截图决定下一个动作。
- 发一个点按、一次滑动,或者一串输入的文字(也可以按键)。
- 再要一张截图确认结果。
- 重复,直到任务做完。
没有无障碍树,也没有针对某个 App 的接口。Agent 知道的全部来自像素,好处是跨 App 都能用,代价是模型必须是视觉模型。
链路:MCP 客户端和手机之间有什么
| 一段 | 传什么 | 走哪 |
|---|---|---|
| MCP 客户端到 CLI | 工具调用和结果 | 电脑上的本地进程 |
| CLI 到板子 | 指令和画面 | 蓝牙 LE |
| iPhone 到板子 | 屏幕 | 板子自己开的 Wi-Fi 热点,AirPlay 镜像 |
| 板子到 iPhone | 指针和键盘输入 | USB HID 鼠标和键盘 |
板子在 iPhone 的「屏幕镜像」列表里显示为 ESP32 Agent。它收到 H.264 码流但不在板上解码。用 CLI 的时候,指令和画面都通过蓝牙送到电脑。手机这一侧,板子插在 USB 口上是标准的 HID 鼠标和键盘;打开「辅助触控」后,点击是轻点,拖动是滑动。
热点没有外网,所以镜像期间手机上需要联网的 App 会走蜂窝数据。
让工具更可靠的设计细节
相对指针怎么处理
USB 鼠标报的是移动量,不是坐标。系统跟踪指针,把它归位到角落以获得一个已知原点。要精确点按时先晃一下指针,在屏幕上定位,再修正偏差。你的 Agent 因此可以按屏幕坐标思考,不用自己管指针漂移。
画面稳定判断
每个动作之后系统会等画面稳定,并报告有没有变化。对 Agent 来说这是个有用的信号:点完之后画面没变,通常说明点错了,或者 App 还在加载。
暂停与恢复
板子、热点或镜像链路断了,运行会暂停,恢复后从同一步继续。
吞吐和限制
设计提示词和超时时间时,按这些数字来:
- 蓝牙 LE 大约 300–500 kbps。镜像画面是 480×1040,最高 5 fps。
- 每一步要几秒,大部分时间花在模型上。
- 键盘只能输入 ASCII,非 ASCII 文字打不出来。
- iOS 不镜像密码输入、Apple Pay 和 DRM 视频,这些画面 Agent 什么也看不到。
- 手机锁屏后镜像停止,跑长任务时留意自动锁屏时间。
- 横屏 App 目前不支持。
硬件清单
- Seeed Studio XIAO ESP32S3 标准版,8 MB 闪存、8 MB PSRAM(约 40 元)。其他带原生 USB、内存相同的 ESP32-S3 板子理论上也行,但没有测过。
- iPhone XS 或更新机型,iOS 18 或更高版本,开启蜂窝数据。
- 短的 USB-C 转 USB-C 数据线,约 30 厘米。Lightning 机型需要 Lightning 转 USB 相机转换器。
- 电脑上装 Chrome 或 Edge,用来刷固件。
不想让电脑参与
同一块板子也能配 iPhone 上的 ESP32 Agent App,通过 TestFlight 分发。那种模式下 App 自己解码画面,把截图发给任意兼容 OpenAI 接口的视觉模型,规划器和执行器都在手机上跑。运行记录存在手机里,可以导出成轨迹:进「运行」,打开某一次,点 ⋯,选「导出轨迹」。想对比 App 的运行和 MCP Agent 的运行,这个很有用。
许可
源码在 GitHub,MIT 许可,固件里的 AirPlay 接收器除外,那部分是 GPL-3.0。接进自己的技术栈之前,CLI 和服务器代码都可以先读一遍。
其他 iOS MCP 做法
Manina AI 是把手机接到 MCP 服务器后面的一种办法。下面这张表只用本站已经写过的内容:模拟器、WebDriverAgent,以及 USB HID 板子。它不是对其他所有项目的评测。
| 做法 | 真机 | 要 Mac 吗 | 开发者账号 | 越狱 |
|---|---|---|---|---|
| 基于模拟器的 MCP | 不是。解决方案页写过,模拟器不会配对真实的蓝牙配件,也不像人们随身带的那部手机。 | 要。那条路标的是 Mac + Xcode。 | 这些文档没有说打开模拟器需要一个。 | 不用 |
| WebDriverAgent | 是。它装在每台手机上。也可以配模拟器。 | 要。一台装了 Xcode 的 Mac。 | 要。付费的 Apple Developer Program,或者免费 Apple ID(签名每 7 天过期)。还要打开开发者模式。 | 不用 |
| Manina AI USB HID | 是。板子插在 iPhone 上。 | 日常使用不用。CLI 能在 macOS、Linux 和 Windows 上跑。刷固件用 Chrome 或 Edge,这三边都可以,做一次。 | 对已经装在手机上的 App,不用。 | 不用 |
快捷指令、蓝牙 HID、USB HID 和屏幕镜像的更长比较在不越狱的 iPhone 自动化。你自己刷的板子不是插上就能用的那件:加入 Manina AI 设备等候名单。
下一步
照着安装指南刷好板子、注册服务器。完整命令说明在 CLI 文档。标准版板子在哪里买,见哪里买 XIAO ESP32S3。
相关:从 Claude Code 操作 iPhone · 让 OpenClaw 操作 iPhone · 怎么让 AI 操作 iPhone · 工作原理