ESP32 Agent
有这么一个 MCP 服务器，能驱动一台实体 iPhone
用模型上下文协议（MCP）做东西的人，常常希望 Agent 能像用文件系统、用浏览器那样，去用一台真实的 iPhone。Handsy 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 和服务器代码都可以先读一遍。