Icemoon — control a real iPhone with AI MCP server

Icemoon MCP Server — control real iPhones from Claude

Give your AI hands. Icemoon exposes physical iPhones to Claude (and any MCP-compatible client) through a local Model Context Protocol server. The AI reads the device screen, plans multi-step tasks, and executes them with human-like touch — on stock iOS, no jailbreak.

This repository is the official documentation and integration reference for the MCP server that ships inside the Icemoon app. The server itself is bundled with the app (commercial, closed source); everything you need to connect it to your MCP client is documented here.

Website: icemoon.app · MCP overview: icemoon.app/mcp · Install guide: icemoon.app/install

What it does

┌────────────┐     MCP (stdio)     ┌──────────────────┐     USB      ┌────────────┐
│   Claude   │ ◄─────────────────► │  Icemoon MCP     │ ◄──────────► │  iPhone(s) │
│  (or any   │                     │  server + app    │              │  stock iOS │
│ MCP client)│                     │  on your Mac     │              │            │
└────────────┘                     └──────────────────┘              └────────────┘

• Sees the screen as structure, not pixels — real UI elements (buttons, labels, text fields) with identifiers and coordinates.
• Touches like a hand, not a script — every swipe follows a unique Bezier curve, taps carry natural timing jitter, typing goes through the real iOS keyboard.
• Plans in the open — for multi-step tasks the AI creates a plan you watch progress live on the Icemoon dashboard.
• Drives a fleet — connections are pooled; the AI switches between connected iPhones instantly or targets a specific device per call.
• Runs locally — the MCP server and the devices live on your Mac. Nothing goes to Icemoon's servers.

Requirements

• macOS 13+ on Apple Silicon (M1 or newer)
• Icemoon installed and activated — the MCP server is included in the Farm and Scale plans
• One or more iPhones connected over USB (stock iOS, no jailbreak — setup guide)

Quick start (Claude Desktop)

1. Install Icemoon and connect an iPhone — step-by-step guide.
2. In the Icemoon app, open AI Copilot → Install to Claude Desktop. The app registers the server (named automation-studio) in ~/Library/Application Support/Claude/claudedesktopconfig.json automatically, with its bundled Python runtime — nothing to install by hand.
3. Restart Claude Desktop. The device tools are now available in every chat.

Ask something like:

Open Settings on my iPhone, turn on Do Not Disturb, and verify it stuck.

Via npm (any MCP client)

icemoon-mcp is a tiny launcher: it finds the installed Icemoon app and hands stdio to the server bundled inside it. No Python to install, no paths to look up.

{
  "mcpServers": {
    "icemoon": {
      "command": "npx",
      "args": ["-y", "icemoon-mcp"]
    }
  }
}

The launcher itself is MIT-licensed and has zero dependencies — read it, it is about a hundred lines. It does nothing on its own: the Icemoon app must be installed and licensed, otherwise it prints where to get it and exits.

If an AI agent is doing the setup for you, point it at llms-install.md — the prerequisites to check, the config to write, and what each failure message means.

Manual configuration (Claude Code, Cursor, other MCP clients)

Shortened. The full README is on GitHub.