Icemoon — Claude Code MCP server: drive a physical 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.
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-mcpWhat Icemoon — control a real iPhone with AI 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.
What it helps with
- 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 for the agent
- 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.
How to install Icemoon — control a real iPhone with AI
Platform CLI
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-mcpReplace <…> with your own values
Platform CLI
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-mcpReplace <…> with your own values
Config file
{
"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
Config file
{
"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
Platform CLI
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-mcpReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Icemoon — control a real iPhone with AI
How do I install Icemoon in Claude Code?
Run claude mcp add automation-studio -- npx -y icemoon-mcp. If the app lives elsewhere or the dashboard uses another address, use the variant with variables: `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`.
What does Icemoon do?
It gives an agent screen access and input control on a physical iPhone: reading UI elements, tapping, swiping, typing, and chaining those steps into tasks. A local server on your Mac handles the traffic over USB.
What is required for the server to work?
An Apple Silicon Mac running macOS 13 or newer, the Icemoon app installed with an active Farm or Scale plan, and an iPhone connected by USB. Keep the app open, since it accepts connections on the local dashboard.
