# Icemoon — control a real iPhone with AI

A local MCP server that lets the model read a real iPhone's screen and carry out multi-step tasks on it with taps and swipes.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI
- Author: icemoon-dev
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/icemoon-dev/icemoon-mcp
- Updated: 2026-08-03
- HTML: https://affpapa.org/en/nevibecode/mcp/icemoon-control-a-real-iphone-with-ai

## What it does

It runs on your Mac and speaks MCP over stdio, handing the agent a toolset for phones plugged in over USB. The screen arrives as structured elements with identifiers and coordinates, so the model works with buttons and fields rather than an image. Gestures follow uneven paths with jittered timing, and text enters through the actual iOS keyboard. Stock iOS is enough; no jailbreak.

The tool list covers device discovery, screen reading, taps and swipes, app launching, batched action runs, plans whose progress shows on a dashboard, clipboard access, video capture, delayed jobs and TOTP generation. Connections sit in a pool, so the model hops between phones or targets one with `port=`.

There is a catch. The server ships inside the Icemoon app, which is commercial and closed source; this repository only documents it. You need macOS 13 or newer on Apple Silicon, an active Farm or Scale plan, and at least one phone on a cable. The app has to stay running because the server talks to its local dashboard on `http://127.0.0.1:8088`. The `icemoon-mcp` launcher is a thin finder: with no licensed app present it prints where to get one and quits.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `ICEMOON_APP`, `ICEMOON_DASHBOARD_URL` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env ICEMOON_APP=<ICEMOON_APP> --env ICEMOON_DASHBOARD_URL=<ICEMOON_DASHBOARD_URL> --transport stdio icemoon-control-a-real-iphone-with-ai -- npx -y icemoon-mcp
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add icemoon-control-a-real-iphone-with-ai --env ICEMOON_APP=<ICEMOON_APP> --env ICEMOON_DASHBOARD_URL=<ICEMOON_DASHBOARD_URL> -- npx -y icemoon-mcp
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "icemoon-control-a-real-iphone-with-ai": {
            "command": "npx",
            "args": [
                "-y",
                "icemoon-mcp"
            ],
            "env": {
                "ICEMOON_APP": "<ICEMOON_APP>",
                "ICEMOON_DASHBOARD_URL": "<ICEMOON_DASHBOARD_URL>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "icemoon-control-a-real-iphone-with-ai": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "icemoon-mcp"
            ],
            "env": {
                "ICEMOON_APP": "<ICEMOON_APP>",
                "ICEMOON_DASHBOARD_URL": "<ICEMOON_DASHBOARD_URL>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e ICEMOON_APP=<ICEMOON_APP> -e ICEMOON_DASHBOARD_URL=<ICEMOON_DASHBOARD_URL> icemoon-control-a-real-iphone-with-ai npx -y icemoon-mcp
```
Replace <…> with your own values

## When to use it
- walk a freshly installed app through onboarding and capture every screen
- replay a saved automation across all attached phones and flag the failing one
- reach the checkout screen in the app on each device and film the flow
- schedule a recurring task on a calendar and fire it across several phones
- pull a TOTP code during a sign-in flow

## Example prompts
- Open Settings on my iPhone, switch on Do Not Disturb, and confirm it stuck.
- Run the saved "morning report" automation on every connected iPhone and tell me which device fails.

## Similar
- [mobile-mcp](https://affpapa.org/en/nevibecode/mcp/mobile-mcp.md) — MCP server · ★ 10025
- [mobilerun](https://affpapa.org/en/nevibecode/mcp/mobilerun.md) — MCP server · ★ 9833
- [e2e](https://affpapa.org/en/nevibecode/mcp/e2e.md) — MCP server · ★ 11962
- [XcodeBuildMCP](https://affpapa.org/en/nevibecode/mcp/xcodebuildmcp.md) — MCP server · ★ 6511
- [ShipSwift](https://affpapa.org/en/nevibecode/mcp/shipswift.md) — MCP server · ★ 3244
- [agent-device](https://affpapa.org/en/nevibecode/mcp/agent-device.md) — MCP server · ★ 5158

---
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