ESP32 Agent

To control an iPhone from Claude Code, add one MCP server and plug in a small board

Claude Code already reads files and runs commands on your computer. With Handsy CLI it can also see an iPhone screen and tap on it. The phone stays stock: no jailbreak and no developer account for daily use. A Seeed Studio XIAO ESP32S3 sits on the phone's USB port as a mouse and keyboard, receives the phone's mirrored screen, and passes everything to your terminal over Bluetooth.

This is useful when the thing you are working on lives on the phone: an iOS app you are building, a web page in mobile Safari, or a chore that only exists in a phone app.

The short version

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

The npx command installs and runs Handsy CLI. The claude mcp add command registers it as an MCP server named esp32agent, so Claude Code can call it in any session. The rest of this page covers the hardware and what a session looks like.

Before you run the commands

You need	Details
A flashed board	XIAO ESP32S3, standard version, 8 MB flash and 8 MB PSRAM, about $7
A browser	Chrome or Edge on your computer, to flash firmware
An iPhone	XS or newer, iOS 18 or later, cellular data on
A data cable	USB-C to USB-C, about 30 cm, not charge-only; Lightning phones add a Lightning to USB Camera Adapter
Bluetooth	On the computer running Claude Code

The board is powered by the phone, so once it is flashed it does not need to stay attached to your computer. Claude Code reaches it over Bluetooth.

Connecting the pieces

Flash the firmware onto the board from Chrome or Edge using the install page.
Plug the board into the iPhone with the data cable.
On the iPhone, turn on AssistiveTouch so the board's clicks act as taps and drags act as swipes.
Join the board's Wi-Fi hotspot and choose ESP32 Agent in Screen Mirroring.
On your computer, run npx -y esp32agent to confirm the CLI can see the board.
Run claude mcp add esp32agent -- esp32agent mcp.
Start Claude Code and ask it to do something on the phone.

The board's hotspot has no internet. That is fine for Claude Code, which runs on your computer, but any app on the phone that needs a connection during the task will use cellular data.

What a session looks like

You describe the goal in a normal prompt, for example: "On the iPhone, open Settings and tell me which iOS version is installed." Claude Code then works through a loop with the MCP tools:

It asks for a screenshot. The CLI pulls the current frame from the board over Bluetooth.
It picks an action: a tap at a point, a swipe, or typed text.
The CLI sends the action to the board, and the board moves the USB pointer or types on the phone.
It asks for another screenshot to check what changed.

Because the USB pointer is relative, the system keeps track of it, re-homes it in a corner, and before a precise tap wiggles it, finds it on screen and corrects the miss. After each action it waits for the screen to settle and reports whether anything changed. If the board, hotspot or mirroring link drops, the run pauses and picks up at the same step.

Coding-agent workflows this fits

Checking your own iOS app

After a code change and a build, ask Claude Code to open the app on the phone, walk through a flow, and describe what it sees on each screen. It is reading the real device, not a simulator.

Mobile web checks

Point it at a page in Safari on the phone and have it scroll, tap through menus and report layout problems in plain words.

Repetitive phone chores

Tasks that have no API, such as toggling a setting in several apps, can be written as a prompt and repeated.

Setting expectations

This is slow compared with code tools, and you should plan for that.

Bluetooth LE moves about 300–500 kbps, so screenshots are 480×1040 and video is at most 5 fps.
A step takes a few seconds, and most of that is model time.
Typing is ASCII only.
iOS will not mirror passcode entry, Apple Pay or DRM video, so those screens are blank to the agent.
If the phone locks, mirroring stops. Raise auto-lock time for long sessions.
Landscape apps are not supported yet.

Keep tasks short and specific, and break long flows into several prompts.

Without Claude Code

The same board also pairs with the ESP32 Agent app on the iPhone (public beta through TestFlight), which runs its own planner and actor against any OpenAI-compatible vision model. Other MCP-capable agents can use the CLI with the same esp32agent mcp command shape.

The code

Everything is on GitHub, MIT licensed, except the firmware's AirPlay receiver, which is GPL-3.0.

Set it up

Flash your board and connect the phone with the install guide, then check flags and tool details in the CLI docs.