{"_id":"icemoon-mcp","_rev":"2-aa736e11e2cda5145fee28be146713f5","name":"icemoon-mcp","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"icemoon-mcp","version":"1.0.0","keywords":["mcp","model-context-protocol","ios","iphone","automation","device-farm","claude","ai-agent"],"author":{"url":"https://icemoon.app","name":"Icemoon","email":"hello@icemoon.app"},"license":"MIT","_id":"icemoon-mcp@1.0.0","maintainers":[{"name":"icemoon-dev","email":"salam.vsem.da@gmail.com"}],"homepage":"https://icemoon.app/mcp","bugs":{"url":"https://github.com/icemoon-dev/icemoon-mcp/issues","email":"hello@icemoon.app"},"os":["darwin"],"bin":{"icemoon-mcp":"bin/icemoon-mcp.mjs"},"cpu":["arm64"],"dist":{"shasum":"15f6ef42e605ea64de9f013c87982680e89337be","tarball":"https://registry.npmjs.org/icemoon-mcp/-/icemoon-mcp-1.0.0.tgz","fileCount":4,"integrity":"sha512-aJhVahtkW1swTn7Flpl96MdGiO9PynpzNojP8MKpO+ccOD5UI78Y0XKyFlcwG78x/RuW8JcC8Lh8xZZHpx/AGQ==","signatures":[{"sig":"MEQCIDRrGnhI40WJJe8/k+uY9LrxLcvu1X6oTaGoOoip5eH5AiAI2WCIC1/9V/dru7rb1zurxr3FdotDo8GIY0xoESJOZg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":13738},"type":"module","engines":{"node":">=18"},"gitHead":"e9120ac69334dae94941869bf3121f163eaf17e2","_npmUser":{"name":"icemoon-dev","email":"salam.vsem.da@gmail.com"},"repository":{"url":"git+https://github.com/icemoon-dev/icemoon-mcp.git","type":"git"},"_npmVersion":"11.11.1","description":"MCP server for controlling real, physical iPhones with AI — no jailbreak. Launcher for the Icemoon macOS app.","directories":{},"_nodeVersion":"25.8.2","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/icemoon-mcp_1.0.0_1785566376072_0.18923438374776635","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"icemoon-mcp","version":"1.0.1","mcpName":"app.icemoon/automation-studio","description":"MCP server for controlling real, physical iPhones with AI — no jailbreak. Launcher for the Icemoon macOS app.","keywords":["mcp","model-context-protocol","ios","iphone","automation","device-farm","claude","ai-agent"],"homepage":"https://icemoon.app/mcp","bugs":{"url":"https://github.com/icemoon-dev/icemoon-mcp/issues","email":"hello@icemoon.app"},"repository":{"type":"git","url":"git+https://github.com/icemoon-dev/icemoon-mcp.git"},"license":"MIT","author":{"name":"Icemoon","email":"hello@icemoon.app","url":"https://icemoon.app"},"type":"module","bin":{"icemoon-mcp":"bin/icemoon-mcp.mjs"},"engines":{"node":">=18"},"os":["darwin"],"cpu":["arm64"],"gitHead":"72f1445839c85fec3aedddaac70f211ca3e6939d","_id":"icemoon-mcp@1.0.1","_nodeVersion":"25.8.2","_npmVersion":"11.11.1","dist":{"integrity":"sha512-mnvP76vFGa+lbZMcVJfuofWB4THqLGwxhtw9BL88Q0leWFygFVfiD2Zw2EUbR7t2N4rFfR9a1/PWD8mOxWctsQ==","shasum":"bdae4c52f0e699b85b4ff8e72e8723f25cd2e587","tarball":"https://registry.npmjs.org/icemoon-mcp/-/icemoon-mcp-1.0.1.tgz","fileCount":4,"unpackedSize":13784,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDAParmbptNqeDOpjqoZas2FU/RHlMuFuhUhtnUISeGoQIgfUwwZGErdI3ISbbuRnNjd3liBhOVTtAx9dJ0U7PvsFk="}]},"_npmUser":{"name":"icemoon-dev","email":"salam.vsem.da@gmail.com"},"directories":{},"maintainers":[{"name":"icemoon-dev","email":"salam.vsem.da@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/icemoon-mcp_1.0.1_1785566662112_0.9120497227575555"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-01T06:39:36.029Z","modified":"2026-08-01T06:44:22.406Z","1.0.0":"2026-08-01T06:39:36.224Z","1.0.1":"2026-08-01T06:44:22.253Z"},"bugs":{"url":"https://github.com/icemoon-dev/icemoon-mcp/issues","email":"hello@icemoon.app"},"author":{"name":"Icemoon","email":"hello@icemoon.app","url":"https://icemoon.app"},"license":"MIT","homepage":"https://icemoon.app/mcp","keywords":["mcp","model-context-protocol","ios","iphone","automation","device-farm","claude","ai-agent"],"repository":{"type":"git","url":"git+https://github.com/icemoon-dev/icemoon-mcp.git"},"description":"MCP server for controlling real, physical iPhones with AI — no jailbreak. Launcher for the Icemoon macOS app.","maintainers":[{"name":"icemoon-dev","email":"salam.vsem.da@gmail.com"}],"readme":"# 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\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\n50 tools across eight groups — full reference with parameters in [docs/tools.md](docs/tools.md).\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` `get_nav_map` `screenshot_save` | Structured UI reading — elements, screen fingerprints, app navigation maps |\n| 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 |\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` | Fetch external data mid-task (with SSRF-safe URL validation) |\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---\n\n*Icemoon — automate real iPhones with human-like touch, from your Mac, no jailbreak.*\n","readmeFilename":"README.md"}