Handsy AI
GitHub

ESP32 Agent

要从 Claude Code 操作 iPhone，加一个 MCP 服务器、插一块小板子就行

Claude Code 已经能在你电脑上读文件、跑命令。接上 Handsy CLI 之后，它还能看见 iPhone 的屏幕、在上面点按。手机保持原样：不越狱，日常使用也不用开发者账号。一块 Seeed Studio XIAO ESP32S3 插在手机的 USB 口上，充当鼠标和键盘，接收手机镜像出来的画面，并通过蓝牙把这些交给你的终端。

这在你手上的活儿本来就在手机里时特别好用：你在做的 iOS App、移动版 Safari 里的一个网页，或者只存在于手机 App 里的琐事。

最短版本

npx -y esp32agent
claude mcp add esp32agent -- esp32agent mcp

npx 那条命令安装并运行 Handsy CLI。claude mcp add 把它注册成名为 esp32agent 的 MCP 服务器，之后 Claude Code 在任何会话里都能调用。剩下的篇幅讲硬件和一次会话是什么样。

跑命令之前

需要说明
刷好固件的板子XIAO ESP32S3 标准版，8 MB 闪存、8 MB PSRAM，约 40 元
一个浏览器电脑上的 Chrome 或 Edge，用来刷固件
一台 iPhoneXS 或更新机型，iOS 18 或更高版本，开启蜂窝数据
一根数据线USB-C 转 USB-C，约 30 厘米，不能是只能充电的；Lightning 机型再加 Lightning 转 USB 相机转换器
蓝牙跑 Claude Code 的电脑上要开着

板子由手机供电，所以刷好固件之后不用再插在电脑上。Claude Code 通过蓝牙连它。

把各段接起来

  1. 在电脑上用 Chrome 或 Edge 打开安装页，把固件刷进板子。
  2. 用数据线把板子插到 iPhone 上。
  3. 在 iPhone 上打开「辅助触控」，板子的点击才会变成轻点、拖动变成滑动。
  4. 连上板子的 Wi-Fi 热点，在「屏幕镜像」里选 ESP32 Agent。
  5. 在电脑上跑 npx -y esp32agent，确认 CLI 能看到板子。
  6. 跑 claude mcp add esp32agent -- esp32agent mcp。
  7. 打开 Claude Code，让它去手机上做件事。

板子的热点没有外网。Claude Code 跑在电脑上，不受影响，但任务期间手机上需要联网的 App 会走蜂窝数据。

一次会话是什么样

你用平常的话说目标，比如「在 iPhone 上打开设置，告诉我现在装的是哪个 iOS 版本」。然后 Claude Code 就通过 MCP 工具循环：

  • 要一张截图。CLI 通过蓝牙从板子取当前这一帧。
  • 挑一个动作：在某个点轻点、滑动，或者输入文字。
  • CLI 把动作发给板子，板子移动 USB 指针或者在手机上打字。
  • 再要一张截图，看有什么变化。

USB 指针是相对的，所以系统自己盯着它、把它归位到角落；要精确点按时先晃一下，找到它在屏幕上的位置，再修正偏差。每个动作之后它会等画面稳定，并报告有没有变化。板子、热点或镜像链路断了，运行会暂停，恢复后从同一步接着来。

适合哪些编码场景

检查自己的 iOS App

改完代码、打好包之后，让 Claude Code 在手机上打开 App，走一遍流程，说清每个界面上看到了什么。它读的是真机，不是模拟器。

移动网页检查

让它打开手机 Safari 里的某个页面，滚动、点菜单，用大白话报告哪里排版有问题。

重复的手机琐事

没有接口的事，比如在好几个 App 里改同一个设置，可以写成一段提示词反复跑。

先说清预期

跟写代码的工具比，这个慢，要提前算进去。

  • 蓝牙 LE 大约 300–500 kbps，所以截图是 480×1040，画面最高 5 fps。
  • 一步要几秒，大部分时间是模型。
  • 只能输入 ASCII。
  • iOS 不会镜像密码输入、Apple Pay 和 DRM 视频，这些画面 Agent 看到的是空白。
  • 手机锁屏后镜像会停。跑长会话记得把自动锁屏时间调长。
  • 横屏 App 目前不支持。

任务写短一点、具体一点，长流程拆成几段提示词。

不用 Claude Code 也行

同一块板子也能配 iPhone 上的 ESP32 Agent App（TestFlight 公开测试）。那种模式下 App 自己跑规划器和执行器，对着任意兼容 OpenAI 接口的视觉模型。其他支持 MCP 的 Agent，用同样的 esp32agent mcp 形状接就行。

代码

全部在 GitHub，MIT 许可，固件里的 AirPlay 接收器除外，那部分是 GPL-3.0。

装起来

照着安装指南刷板子、连手机，参数和工具细节看 CLI 文档。

相关：iPhone 的 MCP 服务器 · ESP32 iPhone Agent 安装 · 工作原理