{
  "markdown": "# Icemoon MCP Server — control real iPhones from Claude\n\n**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**.\n\n> 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.\n\n**Website:** [icemoon.app](https://icemoon.app) · **MCP overview:** [icemoon.app/mcp](https://icemoon.app/mcp) · **Install guide:** [icemoon.app/install](https://icemoon.app/install)\n\n---\n\n## What it does\n\n```\n┌────────────┐     MCP (stdio)     ┌──────────────────┐     USB      ┌────────────┐\n│   Claude   │ ◄─────────────────► │  Icemoon MCP     │ ◄──────────► │  iPhone(s) │\n│  (or any   │                     │  server + app    │              │  stock iOS │\n│ MCP client)│                     │  on your Mac     │              │            │\n└────────────┘                     └──────────────────┘              └────────────┘\n```\n\n- **Sees the screen as structure, not pixels** — real UI elements (buttons, labels, text fields) with identifiers and coordinates.\n- **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.\n- **Plans in the open** — for multi-step tasks the AI creates a plan you watch progress live on the Icemoon dashboard.\n- **Drives a fleet** — connections are pooled; the AI switches between connected iPhones instantly or targets a specific device per call.\n- **Runs locally** — the MCP server and the devices live on your Mac. Nothing goes to Icemoon's servers.\n\n## Requirements\n\n- macOS 13+ on Apple Silicon (M1 or newer)\n- [Icemoon](https://icemoon.app) installed and activated — the MCP server is included in the **Farm** and **Scale** plans\n- One or more iPhones connected over USB (stock iOS, no jailbreak — [setup guide](https://icemoon.app/install))\n\n## Quick start (Claude Desktop)\n\n1. Install Icemoon and connect an iPhone — [step-by-step guide](https://icemoon.app/install).\n2. 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.\n3. Restart Claude Desktop. The device tools are now available in every chat.\n\nAsk something like:\n\n> *Open Settings on my iPhone, turn on Do Not Disturb, and verify it stuck.*\n\n## Via npm (any MCP client)\n\n`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.\n\n```json\n{\n  \"mcpServers\": {\n    \"icemoon\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"icemoon-mcp\"]\n    }\n  }\n}\n```\n\nThe 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.\n\nIf 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.\n\n| Variable | Default | Purpose |\n| --- | --- | --- |\n| `ICEMOON_APP` | `/Applications/AutomationStudio.app` | Path to the app bundle, if installed elsewhere |\n| `ICEMOON_DASHBOARD_URL` | `http://127.0.0.1:8088` | Where the running Icemoon app listens |\n\n## Manual configuration (Claude Code, Cursor, other MCP clients)\n\nIf 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:\n\n```json\n{\n  \"mcpServers\": {\n    \"automation-studio\": {\n      \"command\": \"/Applications/AutomationStudio.app/Contents/Resources/mcp_python/bin/python3\",\n      \"args\": [\"/Applications/AutomationStudio.app/Contents/Resources/mcp_server.py\"],\n      \"env\": {\n        \"DASHBOARD_URL\": \"http://127.0.0.1:8088\",\n        \"PYTHONPATH\": \"/Applications/AutomationStudio.app/Contents/Resources/mcp_libs\"\n      }\n    }\n  }\n}\n```\n\nNotes:\n- `DASHBOARD_URL` is the local Icemoon dashboard (default port `8088`); the app must be running.\n- 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`.\n\n## Tools\n\n53 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).\n\n| Group | Tools | What the AI gets |\n|---|---|---|\n| Devices & session | `list_devices` `connect_device` `disconnect_device` `device_status` `get_metrics` | Discover running devices, pooled connections, per-call `port=` targeting |\n| 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 |\n| 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 |\n| 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 |\n| 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 |\n| 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 |\n| Scheduling & scripts | `schedule_task` `list_scheduled_tasks` `delete_scheduled_task` `list_saved_scripts` | Fire saved automations later, on a calendar, across the fleet |\n| Utilities | `http_request` `get_2fa_code` | Fetch external data mid-task (SSRF-safe URL validation); generate TOTP codes for sign-in flows |\n\n## Example prompts\n\n- *Go through the onboarding of the app I just installed and screenshot every screen.*\n- *Run the saved “morning report” automation on all connected iPhones and tell me if any device fails.*\n- *Navigate to the checkout screen in our app on every device and record a video of the flow.*\n- *Every day at 9:00, open the app, refresh the feed, and save a screenshot — schedule it.*\n\n## Security & privacy\n\n- The server binds locally and talks only to the Icemoon dashboard on `127.0.0.1`; devices are attached over USB.\n- Every tool call is written to a local audit log (sensitive parameters masked).\n- `http_request` validates URLs and blocks private-network targets.\n- Screen content reaches only the MCP client you connect (e.g. Claude), only while it's working for you.\n\n## FAQ\n\n**Is this open source?** The docs, examples, and manifest in this repo are MIT. The server ships inside the commercial Icemoon app.\n\n**Does it work without the Icemoon app?** No — the MCP server is the AI-facing surface of the app's automation engine.\n\n**Android?** No, iOS only. That focus is where the human-like input and no-jailbreak setup come from.\n\n**Which plans include it?** Farm and Scale — see [pricing](https://icemoon.app/#pricing).\n\n## Related\n\n- [**icemoon-dev/icemoon**](https://github.com/icemoon-dev/icemoon) — the main project: documentation, issue tracker, release notes\n- [`icemoon-mcp` on npm](https://www.npmjs.com/package/icemoon-mcp)\n- [icemoon.app](https://icemoon.app) — the product\n\n---\n\n*Icemoon — automate real iPhones with human-like touch, from your Mac, no jailbreak.*\n",
  "bytes": 8239,
  "sha": "30512bcf26b14bdb5a957c66c32a3a93d1e81cfaeb2a586abb287df8921734e4",
  "repo_slug": "icemoon-dev/icemoon-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_app_icemoon_automation_studio_df187ac1/readme"
}