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](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.

| 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

50 tools across eight groups — full reference with parameters in [docs/tools.md](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](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.*