Guides
OpenClaw controls a real iPhone through the Handsy MCP server
OpenClaw can use a real iPhone the same way Claude Code can: through Handsy CLI. The CLI is a local MCP server. The Handsy skill that describes that server is published on ClawHub as handsy. These docs do not add an OpenClaw-only command. They tell every MCP client to run esp32agent mcp on the computer that can see the board.
The phone stays stock. No jailbreak, and no Apple developer account for daily use. A Seeed Studio XIAO ESP32S3 sits on the phone’s USB port as a keyboard and mouse, receives the mirrored screen, and passes it to your computer over Bluetooth.
The short version
npx -y esp32agentThat installs and runs Handsy CLI. The MCP server is the same package with the mcp argument. The skill on ClawHub publishes this shape for clients that take a JSON config:
{
"mcpServers": {
"esp32agent": {
"command": "npx",
"args": ["-y", "esp32agent", "mcp"]
}
}
}Point OpenClaw at that local server the way you point it at any other stdio MCP server, or install the ClawHub skill handsy the way you install your other ClawHub skills. Pairing is not done by the MCP tools. The steps are in the CLI docs.
Before you connect it
| You need | Details |
|---|---|
| A flashed board | XIAO ESP32S3, standard version, 8 MB flash and 8 MB PSRAM. Firmware v0.2.2 or later for the CLI. The browser installer writes it. |
| A browser | Chrome or Edge on a computer, once, to flash |
| 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. |
| The computer running OpenClaw | Bluetooth, so the CLI can reach the board. A remote agent with no access to this computer cannot reach the board by itself. |
The board is powered by the phone. OpenClaw does not have to be on a Mac. Handsy CLI runs on macOS, Linux, and Windows.
Connecting the pieces
- Flash the firmware from Chrome or Edge on the install page. Use the TestFlight channel if you need the CLI firmware.
- Plug the board into the iPhone with the data cable. Attach the antenna first.
- Turn on AssistiveTouch, so a click is a tap and a drag is a swipe.
- Join the board’s Wi-Fi hotspot and choose ESP32 Agent in Screen Mirroring.
- On the computer, run npx -y esp32agent, then pair. The CLI docs have the devices and pair commands. Run the first pair within three minutes of powering the board.
- Register esp32agent mcp with OpenClaw, or install the ClawHub skill handsy.
- Ask OpenClaw to do one small thing on the phone, and to look at a fresh screenshot after each action.
The board’s hotspot has no internet. OpenClaw runs on the computer, so that is fine. An app on the phone that needs a connection during the task uses cellular data.
What a session looks like
You describe the goal in a normal request, for example: “On the iPhone, open Settings and tell me which iOS version is installed.” The agent then loops with the MCP tools:
- It asks for a screenshot. The CLI pulls the current frame from the board over Bluetooth.
- It picks one action: a tap, a swipe, or typed text.
- The CLI sends that action to the board. The board moves the USB pointer or types on the phone.
- It asks for another screenshot and checks what changed before the next step.
A USB mouse reports movement, not a coordinate. The CLI tracks the pointer, re-homes it, and can correct a miss before a precise tap. There is no accessibility tree. The agent only knows what is in the pixels, so the model has to be able to read a screenshot.
What the docs say it cannot do
- The phone has to stay unlocked and in portrait. Locking stops Screen Mirroring. Landscape apps are not supported yet.
- iOS does not mirror passcode entry, Apple Pay, or DRM-protected video.
- Keyboard input through the CLI is ASCII. Chinese is typed as Pinyin, then the agent picks the candidate.
- The MCP tools do not do the first pairing. That is a terminal step.
- The free AI service inside the iPhone app is a separate path. It does not supply the model OpenClaw uses.
The same server, other agents
Claude Code registers it with claude mcp add esp32agent -- esp32agent mcp. Codex uses codex mcp add esp32agent -- esp32agent mcp. DeepSeek Harness has its own plugin, documented separately. The phone side does not change.
The code
The CLI is on GitHub, MIT licensed, except the firmware’s AirPlay receiver, which is GPL-3.0. The skill files are MIT-0.
Set it up
Flash the board on the install page, then follow the CLI docs for pairing. The tool list is on the iPhone MCP server page. The board you buy yourself is not the Handsy device: that one is a waitlist, at the Handsy device page.
Related: Control an iPhone from Claude Code · where to buy a XIAO ESP32S3 · iPhone automation without jailbreak