Icemoon — control a real iPhone with AI

Icemoon MCP Server — 从 Claude 控制真实 iPhone

赋予 AI 双手。 Icemoon 通过本地 Model Context Protocol 服务，将实体 iPhone 暴露给 Claude（以及任何兼容 MCP 的客户端）。AI 可以读取设备屏幕、规划多步任务，并以接近人类的触控方式执行操作——运行原版 iOS，无需越狱。

本仓库是随 Icemoon 应用一同提供的 MCP 服务的官方文档和集成参考。服务本身捆绑在应用中（商业闭源）；在此可查阅将其连接到 MCP 客户端所需的全部信息。

网站： icemoon.app · MCP 概览： icemoon.app/mcp · 安装指南： icemoon.app/install

---

功能

┌────────────┐     MCP (stdio)     ┌──────────────────┐     USB      ┌────────────┐
│   Claude   │ ◄─────────────────► │  Icemoon MCP     │ ◄──────────► │  iPhone(s) │
│  (or any   │                     │  server + app    │              │  stock iOS │
│ MCP client)│                     │  on your Mac     │              │            │
└────────────┘                     └──────────────────┘              └────────────┘

• 以结构而非像素识别屏幕——识别真实 UI 元素（按钮、标签、文本字段），并提供标识符和坐标。
• 像手一样触控，而非执行脚本——每次滑动都沿独特的贝塞尔曲线进行，点按带有自然的时间抖动，输入通过真实的 iOS 键盘完成。
• 公开规划过程——对于多步任务，AI 会制定计划，你可以在 Icemoon 控制面板上实时查看进度。
• 操控多台设备——连接会被集中管理；AI 可即时切换已连接的 iPhone，也可在每次调用时指定设备。
• 在本地运行——MCP 服务和设备都在你的 Mac 上运行。不会向 Icemoon 的服务器发送任何内容。

系统要求

• Apple 芯片（M1 或更新型号）的 macOS 13+
• 已安装并激活 Icemoon——MCP 服务包含在 Farm 和 Scale 套餐中
• 通过 USB 连接的一台或多台 iPhone（原版 iOS，无需越狱——设置指南）

快速开始（Claude Desktop）

1. 安装 Icemoon 并连接 iPhone——参阅分步指南。
2. 在 Icemoon 应用中，打开 AI Copilot → Install to Claude Desktop。应用会自动将名为 automation-studio 的服务注册到 ~/Library/Application Support/Claude/claude_desktop_config.json，并使用随应用捆绑的 Python 运行时——无需手动安装任何内容。
3. 重启 Claude Desktop。现在，每次聊天都可以使用设备工具。

可以试着这样提问：

在我的 iPhone 上打开“设置”，开启“勿扰模式”，并确认设置已生效。

通过 npm 使用（适用于任何 MCP 客户端）

icemoon-mcp 是一个轻量启动器：它会查找已安装的 Icemoon 应用，并将标准输入输出交给应用内捆绑的服务。无需安装 Python，也无需查找路径。

{
  "mcpServers": {
    "icemoon": {
      "command": "npx",
      "args": ["-y", "icemoon-mcp"]
    }
  }
}

启动器本身采用 MIT 许可，且零依赖——查看源码，代码约一百行。它本身无法独立运行：必须安装并获得许可的 Icemoon 应用，否则它会提示获取方式并退出。

如果由 AI Agent 帮你完成设置，请让它参考 llms-install.md——其中列出了要检查的前置条件、要写入的配置，以及各类故障消息的含义。

变量	默认值	用途
ICEMOON_APP	/Applications/AutomationStudio.app	应用包的路径（若安装在其他位置）
ICEMOON_DASHBOARD_URL	http://127.0.0.1:8088	运行中的 Icemoon 应用监听的地址

手动配置（Claude Code、Cursor 和其他 MCP 客户端）

如果不想通过 npm 使用，任何 MCP 客户端都可以直接运行捆绑的服务——将其指向应用包中的运行时和脚本：

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

注意：

• DASHBOARD_URL 是本地 Icemoon 控制面板地址（默认端口为 8088）；应用必须处于运行状态。
• 具体路径可能因构建版本而异——最简单的方式是先运行一次一键安装，然后从 claude_desktop_config.json 中复制生成的配置块。

工具

共 53 个工具，分为 8 组 — 完整参考文档及参数见 docs/tools.md。同一列表也以机器可读的服务卡片形式发布。

分组	工具	AI 可获取的信息
设备与会话	list_devices connect_device disconnect_device device_status get_metrics	发现正在运行的设备、池化连接、按调用使用 port= 指定目标
屏幕理解	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	结构化读取 UI — 元素、屏幕指纹、应用导航地图
触控与输入	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	合成人类般的手势；通过真实 iOS 键盘输入文字
应用与导航	open_app kill_app get_app_list navigate_to wait_for_screen	navigate_to 一次调用即可前往目标屏幕：检测 → 路径规划 → 执行 → 验证
批处理与计划	run_batch sleep_delay foreach_elements plan_create plan_add_step plan_update_step plan_get	一次往返执行完整操作序列；在仪表板上实时查看计划进度
设备状态	lock_device unlock_device set_location pasteboard_get pasteboard_set video_record set_action_recording	锁定／解锁、剪贴板、屏幕录制、模拟 GPS、操作录制
调度与脚本	schedule_task list_scheduled_tasks delete_scheduled_task list_saved_scripts	稍后按日程在所有设备上运行已保存的自动化任务
实用工具	http_request get_2fa_code	在任务中获取外部数据（安全防 SSRF 的 URL 验证）；为登录流程生成 TOTP 代码

示例提示词

• 完成我刚安装的应用的引导流程，并为每个屏幕截图。
• 在所有已连接的 iPhone 上运行已保存的“morning report”自动化任务，并告知我是否有设备运行失败。
• 在每台设备上的应用中导航到结账屏幕，并录制操作流程。
• 每天 9:00 打开应用、刷新信息流并保存截图 — 请安排此任务。

安全与隐私

• 服务仅在本地绑定，并且只与 127.0.0.1 上的 Icemoon 仪表板通信；设备通过 USB 连接。
• 每次工具调用都会写入本地审计日志（敏感参数会被屏蔽）。
• http_request 会验证 URL，并阻止指向专用网络的请求。
• 屏幕内容只会发送给你连接的 MCP 客户端（例如 Claude），且仅在它为你工作时发送。

常见问题

这是开源的吗？ 本仓库中的文档、示例和清单采用 MIT 许可。服务随商业版 Icemoon 应用一起提供。

没有 Icemoon 应用也能运行吗？ 不行 — MCP 服务是该应用自动化引擎面向 AI 的接口。

支持 Android 吗？ 不支持，仅支持 iOS。专注于 iOS 才能实现人类般的输入和无需越狱的设置。

哪些套餐包含此功能？ Farm 和 Scale — 请参阅定价。

相关链接

• icemoon-dev/icemoon — 主项目：文档、问题跟踪、发行说明
• icemoon-mcp on npm
• icemoon.app — 产品网站

---

Icemoon — 在 Mac 上通过人类般的触控自动操作真实 iPhone，无需越狱。