# Handsy AI

Handsy AI — an MCP server for Claude Code and Codex that links an AI agent to a physical iPhone using an ESP32-S3 board. Controls apps directly via USB HID without requiring a jailbreak.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 5197 repo stars
- Author: onehumanbeing
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/onehumanbeing/esp32-iphone-agent
- Updated: 2026-11-16
- Security check: automated, 2026-11-17 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/mcp/handsy-ai

## What it does

The MCP server executes agent commands on a physical iPhone by sending touch events through a Seeed XIAO ESP32S3 microcontroller. The hardware acts as a USB HID peripheral while device audio streams over AirPlay.

Navigation relies on standard screen elements with AssistiveTouch turned on. The setup requires iOS 18 or newer, the companion app from TestFlight, and board firmware v0.2.4.

The phone uses cellular data while running tasks because the board's hotspot occupies the Wi-Fi connection.

## Requirements
- Needs: Node.js (commands run via npx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add esp32agent -- npx -y esp32agent
```

### Codex

**Platform CLI**
```bash
codex mcp add handsy-ai -- npx -y esp32agent
```

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "handsy-ai": {
            "command": "npx",
            "args": [
                "-y",
                "esp32agent"
            ]
        }
    }
}
```

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "handsy-ai": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "esp32agent"
            ]
        }
    }
}
```

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add handsy-ai npx -y esp32agent
```

## When to use it
- control native iOS apps on an actual phone without jailbreaking
- automate mobile workflows and testing through an AI agent
- capture incoming audio cues from iOS via AirPlay streaming
- operate a phone independently without tethering to Xcode on a Mac

## Example prompts
- Open Duolingo on the connected iPhone and finish the lesson
- Inspect incoming notifications and dismiss active alerts
- Dial the contact number using the stock phone dialer

## Similar
- [ios-mcp-jailbreak-automation](https://affpapa.org/en/nevibecode/skills/ios-mcp-jailbreak-automation.md) — skill · 121 installs
- [Icemoon — control a real iPhone with AI](https://affpapa.org/en/nevibecode/mcp/icemoon-control-a-real-iphone-with-ai.md) — MCP server
- [pi-app](https://affpapa.org/en/nevibecode/prompts/pi-app.md) — prompt · ★ 1754 repo stars
- [mcp](https://affpapa.org/en/nevibecode/mcp/jettydiot-mcp.md) — MCP server
- [iPhone Use](https://affpapa.org/en/nevibecode/mcp/iphone-use.md) — MCP server · ★ 514 repo stars
- [mirroir-mcp](https://affpapa.org/en/nevibecode/mcp/mirroir-mcp.md) — MCP server · ★ 400 repo stars

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
