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

Code

┌────────────┐     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)

Install Icemoon and connect an iPhone — step-by-step guide.
In the Icemoon app, open AI Copilot → Install to Claude Desktop. The app registers the server (named automation-studio) in ~/Library/Application Support/Claude/claude_desktop_config.json automatically, with its bundled Python runtime — nothing to install by hand.
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.

config.json

{
  "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.

Variable	Default	Purpose
`ICEMOON_APP`	`/Applications/AutomationStudio.app`	Path to the app bundle, if installed elsewhere
`ICEMOON_DASHBOARD_URL`	`http://127.0.0.1:8088`	Where the running Icemoon app listens

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

If you would rather not go through npm, any MCP client can run the bundled server directly — point it at the bundle's runtime and script:

config.json

{
  "mcpServers": {
    "automation-studio": {
      "command": "/Applications/AutomationStudio.app/Contents/Resources/mcp_python/bin/python3",
      "args": ["/Applications/AutomationStudio.app/Contents/Resources/mcp_server.py"],
      "env": {
        "DASHBOARD_URL": "http://127.0.0.1:8088",
        "PYTHONPATH": "/Applications/AutomationStudio.app/Contents/Resources/mcp_libs"
      }
    }
  }
}

Notes:

DASHBOARD_URL is the local Icemoon dashboard (default port 8088); the app must be running.
Exact paths can differ per build — the easiest way to get the correct entry is to run the one-click install once and copy the generated block from claude_desktop_config.json.

Tools

53 tools across eight groups — full reference with parameters in docs/tools.md. The same list is published as a machine-readable server card.

Group	Tools	What the AI gets
Devices & session	`list_devices` `connect_device` `disconnect_device` `device_status` `get_metrics`	Discover running devices, pooled connections, per-call `port=` targeting
Screen understanding	`get_visible_elements` `identify_screen` `get_screen_info` `get_screen_map` `get_element_at_position` `find_by_id` `find_by_label` `get_nav_map` `screenshot_save`	Structured UI reading — elements, screen fingerprints, app navigation maps
Touch & input	`tap` `tap_by_id` `tap_by_label` `tap_relative` `double_tap` `touch_hold` `swipe` `swipe_relative` `scroll` `pinch` `type_text` `smart_type` `keyboard_dismiss` `press_button`	Human-like gesture synthesis; typing through the real iOS keyboard
Apps & navigation	`open_app` `kill_app` `get_app_list` `navigate_to` `wait_for_screen`	`navigate_to` walks to a target screen in one call: detect → path → execute → verify
Batching & plans	`run_batch` `sleep_delay` `foreach_elements` `plan_create` `plan_add_step` `plan_update_step` `plan_get`	Whole action sequences in one round-trip; live plan progress on the dashboard
Device state	`lock_device` `unlock_device` `set_location` `pasteboard_get` `pasteboard_set` `video_record` `set_action_recording`	Lock/unlock, clipboard, screen recording, simulated GPS, action recording
Scheduling & scripts	`schedule_task` `list_scheduled_tasks` `delete_scheduled_task` `list_saved_scripts`	Fire saved automations later, on a calendar, across the fleet
Utilities	`http_request` `get_2fa_code`	Fetch external data mid-task (SSRF-safe URL validation); generate TOTP codes for sign-in flows

Example prompts

Go through the onboarding of the app I just installed and screenshot every screen.
Run the saved “morning report” automation on all connected iPhones and tell me if any device fails.
Navigate to the checkout screen in our app on every device and record a video of the flow.
Every day at 9:00, open the app, refresh the feed, and save a screenshot — schedule it.

Security & privacy

The server binds locally and talks only to the Icemoon dashboard on 127.0.0.1; devices are attached over USB.
Every tool call is written to a local audit log (sensitive parameters masked).
http_request validates URLs and blocks private-network targets.
Screen content reaches only the MCP client you connect (e.g. Claude), only while it's working for you.

FAQ

Is this open source? The docs, examples, and manifest in this repo are MIT. The server ships inside the commercial Icemoon app.

Does it work without the Icemoon app? No — the MCP server is the AI-facing surface of the app's automation engine.

Android? No, iOS only. That focus is where the human-like input and no-jailbreak setup come from.

Which plans include it? Farm and Scale — see pricing.

icemoon-dev/icemoon — the main project: documentation, issue tracker, release notes
icemoon-mcp on npm
icemoon.app — the product

Icemoon — automate real iPhones with human-like touch, from your Mac, no jailbreak.

Icemoon — control a real iPhone with AI README