icemoon-mcp

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)

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

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

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:

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

50 tools across eight groups — full reference with parameters in docs/tools.md.

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 get_nav_map screenshot_save	Structured UI reading — elements, screen fingerprints, app navigation maps
Touch & input	tap tap_by_id 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	Fetch external data mid-task (with SSRF-safe URL validation)

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 — automate real iPhones with human-like touch, from your Mac, no jailbreak.