# 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](https://modelcontextprotocol.io) 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](https://icemoon.app) 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](https://icemoon.app) · **MCP overview:** [icemoon.app/mcp](https://icemoon.app/mcp) · **Install guide:** [icemoon.app/install](https://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](https://icemoon.app) 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](https://icemoon.app/install)) ## Quick start (Claude Desktop) 1. Install Icemoon and connect an iPhone — [step-by-step guide](https://icemoon.app/install). 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/claude_desktop_config.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. ```json { "mcpServers": { "icemoon": { "command": "npx", "args": ["-y", "icemoon-mcp"] } } } ``` The launcher itself is MIT-licensed and has zero dependencies — [read it](bin/icemoon-mcp.mjs), 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](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: ```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](docs/tools.md). The same list is published as a machine-readable [server card](https://icemoon.app/.well-known/mcp/server-card.json). | 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](https://icemoon.app/#pricing). ## Related - [**icemoon-dev/icemoon**](https://github.com/icemoon-dev/icemoon) — the main project: documentation, issue tracker, release notes - [`icemoon-mcp` on npm](https://www.npmjs.com/package/icemoon-mcp) - [icemoon.app](https://icemoon.app) — the product --- *Icemoon — automate real iPhones with human-like touch, from your Mac, no jailbreak.*