mcp-ios

mcp-ios

一个用于操控 iPhone/iPad 的 Model Context Protocol 服务，是 mcp-android 的 iOS 对应版本。请先阅读：iOS 的限制本质上比 Android 或 macOS 严格得多，因此本服务采用了实现真实 UI 控制的唯一合法途径。

真实情况

标准 iPhone 不允许后台应用像 Android 的无障碍服务（或 macOS）那样查看和控制其他应用。Apple 的沙盒机制禁止这样做。因此，iOS 上没有类似 Mac/Android 版本的设备端「iOS-use」Agent。可行方案按能力从高到低排列如下：

方案	控制级别	所需条件	备注
Appium + WebDriverAgent (XCUITest) ✅ （本服务）	完整 UI 控制：点击、输入、滑动、读取元素、截屏、启动应用	一台装有 Xcode 的 Mac；通过 USB（或同一网络）连接 iPhone；为设备上的 WDA 签名	真正的「手机操控」。专为自动化/QA 打造，非常适合在个人设备上运行个人 Agent。
Shortcuts	运行用户定义的操作（设置闹钟、发送消息、切换开关）	Shortcuts 应用；URL/x-callback 桥接	无法任意控制 UI，但适合执行安全、明确的操作。此处通过 run_shortcut 提供。
MDM	策略/配置、安装应用	注册	设备管理，而非交互式控制。

本服务实现了 Appium/WDA 方案：它在 Mac 上运行，连接到本地 Appium 服务，由该服务操控已连接 iPhone 上的 WebDriverAgent，并采用与套件中其他服务相同的默认安全 MCP 形式。像 set_alarm 这样的操作也可以通过 Shortcuts（run_shortcut）执行，无需连接设备。

如果你想要完全不连接任何设备、直接从手机本身进行控制，这在 iOS 上是不可能的——要实现这种体验，请在 Fold 7 上使用 mcp-android，或者使用此处提供的 Shortcuts 功能子集。

设置（Appium 方案）

brew install node
npm i -g appium
appium driver install xcuitest
# Xcode + command line tools installed; sign WebDriverAgent to your device once (Xcode)
# Connect the iPhone by USB, Trust the Mac, enable Developer Mode on the device
appium        # starts the Appium server (default http://127.0.0.1:4723)

本服务会在首次调用工具时延迟创建 XCUITest 会话，因此即使 Appium 或设备尚未启动，也可以启动服务——如果无法连接，首次需要设备的调用会返回清晰提示，告知你「启动 appium / 为 WDA 签名 / 连接设备」。

安全模型

关注事项	标志	默认值	影响
服务可以执行哪些操作？	IOS_MODE	read-only	read-only 仅开放检查功能；read-write 增加 UI 控制；admin 增加应用管理。超出当前模式的工具绝不会注册。
哪些应用在管理范围内？	IOS_APP_ALLOWLIST	（全部）	设置后，任何其他 bundle ID 的启动或管理操作都会被拒绝。
哪些应用始终为只读？	IOS_PROTECTED_APPS	com.apple.Preferences、com.apple.springboard	可检查和启动，但绝不会被终止、重置或卸载。
是否可以安装、终止或重置应用？	IOS_ALLOW_MANAGE	false	管理工具需要此选项以及 admin 模式；否则甚至不会公布这些工具。
交互式确认	（自动）	—	terminate_app 和 reset_app 执行前，会通过 MCP elicitation 提示用户批准确切的 bundle ID；不支持 elicitation 的客户端则回退到 IOS_ALLOW_MANAGE 门控。
预览而不操作设备	IOS_DRY_RUN	false	写入/管理工具会验证并记录操作意图，然后返回。
审计跟踪	IOS_AUDIT_LOG	true	每次受保护操作都会向 stderr 输出一行 JSON。

连接设置：IOS_APPIUM_URL（默认 http://127.0.0.1:4723）、IOS_UDID（目标设备）、IOS_BUNDLE_ID（可选的默认应用）。所有变量请参见 .env.example，完整的客户端安装指南请参见 docs/CLIENTS.md。

工具

读取（read-only+）：list_targets、device_info、screenshot、page_source（元素树）、current_app、list_apps

写入（read-write+）：tap、swipe、input_text、press_button（主屏幕/音量）、launch_app、open_url、run_shortcut（通过 Shortcuts）

管理（admin + IOS_ALLOW_MANAGE）：install_app、terminate_app、reset_app（后两项会通过 elicitation 确认；受保护的应用会被拒绝）

screenshot 会返回 MCP 图像内容块，让 Agent 在采取操作前查看屏幕。

快速开始 — 添加到你的 Agent

已发布到 npm，名称为 @dockndevai/mcp-ios。无需克隆或构建 — MCP 客户端会按需通过 npx 运行它。它必须在运行中的 Appium 服务所在的 Mac 上运行。请从 read-only 模式开始。

Claude Code（命令行）

claude mcp add ios -e IOS_APPIUM_URL="http://127.0.0.1:4723" -e IOS_MODE="read-only" -- npx -y @dockndevai/mcp-ios

Claude Desktop · Cursor · Windsurf — 在 claude_desktop_config.json、.cursor/mcp.json 或 ~/.codeium/windsurf/mcp_config.json 中使用相同配置块：

{
  "mcpServers": {
    "ios": {
      "command": "npx",
      "args": [
        "-y",
        "@dockndevai/mcp-ios"
      ],
      "env": {
        "IOS_APPIUM_URL": "http://127.0.0.1:4723",
        "IOS_MODE": "read-only"
      }
    }
  }
}

VS Code（GitHub Copilot，Agent 模式） — 在 .vscode/mcp.json 中：

{
  "servers": {
    "ios": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@dockndevai/mcp-ios"
      ],
      "env": {
        "IOS_APPIUM_URL": "http://127.0.0.1:4723",
        "IOS_MODE": "read-only"
      }
    }
  }
}

示例提示词

• “截取我手机的屏幕并告诉我屏幕上有什么。”
• “打开 Safari 并访问 news.ycombinator.com。”（需要 read-write）
• “运行我的 ‘Good morning’ Shortcut。”（需要 read-write）

从源码运行（开发）

npm install
npm run build
node dist/index.js   # with the environment variables set, and `appium` running

开发

npm run dev
npm test          # security policy + elicitation confirmation (pure; no device needed)
npm run typecheck

策略和 elicitation 测试不依赖外部环境，可在任何地方运行。没有 Mac + Xcode + 已签名的 WDA + 通过线缆连接的 iPhone，便无法对设备驱动流程进行冒烟测试，因此该流程是针对你的真实设备配置构建的。

发布

此服务附带 server.json，用于官方 MCP 注册表；还附带用于验证 npm 所有权的 mcpName。有关发布到 npm 并列入 MCP 注册表、Smithery、Glama、Cursor 和 PulseMCP 的详情，请参见 PUBLISHING.md。

许可证

MIT