AI导哈

iPhone远程控制服务

通过MCP协议从macOS远程控制物理iPhone的服务，支持截图、点击、滑动、文本输入等功能。

  • by yev-yev-yev
  • TypeScript
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 yev-yev-yev/iphone-mcp

使用说明

iphone mcp

从macOS控制物理iPhone的MCP服务器。截取屏幕截图、点击、滑动、键入文本等——所有这些都是通过 模型上下文协议.

用途 iPhone镜像 （macOS Sequoia 15+）而不是WebDriver Agent，因此没有Xcode设置，没有配置文件，也没有XCTest会话来保持活动。只要插上你的iPhone就可以了。

快速开始

# 1. Clone and build
git clone https://github.com/yev-yev-yev/iphone-mcp.git
cd iphone-mcp
corepack enable
yarn install
yarn build

# 2. Check your setup
yarn doctor

# 3. Add to Claude Code
claude mcp add iphone-mcp node /absolute/path/to/iphone-mcp/dist/index.js

就是这样。让克劳德“给我的iPhone截图”以验证它是否正常工作。

运作原理

MCP Client  ──stdio──>  iphone-mcp  ──>  iPhone Mirroring window
                                              ├── screencapture + sharp (PNG screenshot, 1x default)
                                              ├── CGEvent injection (clicks, drags, scroll wheel)
                                              └── AppleScript keystroke (text input)

iPhone镜像 是一个macOS Sequoia应用程序，可以将iPhone的屏幕镜像到macOS窗口。此服务器以编程方式与该窗口交互：

  • 截图 通过 screencapture + sharp --将镜像窗口捕获为PNG格式，调整大小，覆盖网格，并在单个窗口中夹紧尺寸 sharp 管道
  • 点击和滑动 通过 CGEvent （JXA/osascript）——在右侧屏幕坐标处注入鼠标事件
  • 滚动 通过 CGEventCreateScrollWheelEvent --触控板风格的滚轮事件，实现流畅的内容滚动（根据macOS“自然滚动”偏好自动校正）
  • 文本输入 通过AppleScript keystroke --键入所关注的任何领域

需求

  • macOS红杉15+ （iPhone镜像需要它）
  • iOS 18+ 在iPhone上
  • Node.js 24+
  • 相同的Apple ID 已在Mac和iPhone上登录
  • 蓝牙和WiFi 在两台设备上均已启用
  • 通过USB连接的iPhone，可信（接受“信任此计算机？”）

权限

承载MCP服务器的应用程序（例如终端、VS代码、克劳德桌面）需要两个macOS权限：

权限 它允许什么 在哪里授予
无障碍 点击、滑动、滚动、键入（CGEvent注入） 系统设置>隐私和安全>辅助功能
屏幕录制 屏幕截图（屏幕截图） 系统设置>隐私和安全>屏幕录制

服务器 自动提示 对于首次启动时的辅助功能权限，macOS将打开“系统设置”，您可以在其中切换主机应用程序的开关。屏幕录制权限会自动检查。如果未授予任何一个权限，工具响应将包括一条警告消息，指出哪个应用程序需要访问（例如“终端未授予可访问性权限”）。

跑 yarn doctor 检查是否授予了权限。

安装

# Enable Corepack for Yarn 4
corepack enable

# Install dependencies
yarn install

# Build
yarn build

# Verify your environment
yarn doctor

用法

使用克劳德代码

claude mcp add iphone-mcp node /absolute/path/to/iphone-mcp/dist/index.js

然后和克劳德谈谈：

  • “为我的iPhone截图”
  • “点击设置图标”
  • “在设置中向下滚动”
  • “向左滑动到下一个主屏幕页面”
  • “在搜索字段中键入‘hello world’”

使用克劳德桌面

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "iphone": {
      "command": "node",
      "args": ["/absolute/path/to/iphone-mcp/dist/index.js"]
    }
  }
}

重新启动克劳德桌面。

与MCP检查员一起

npx @modelcontextprotocol/inspector node dist/index.js

打开一个web UI，您可以在其中以交互方式浏览和调用所有工具。

开发模式

yarn dev

使用以下命令运行服务器 tsx watch 用于在文件更改时自动重新启动。

工具

屏幕信息

工具 说明 参数
get_screen_info 获取屏幕尺寸和比例因子 无

截图

工具 说明 参数
screenshot 截图（返回PNG图像） 无

用户界面自动化

工具 说明 参数
tap 点击坐标（以屏幕截图像素为单位）。支持多抽头（双抽头、三抽头等） x, y, numTaps?, screenshotDelay?
long_press 在坐标处按住一段时间 x, y, duration （秒）， screenshotDelay?
swipe 在两点之间滑动——最适合定向手势（关闭、拉刷新、拖放） startX, startY, endX, endY, duration?, easing?, screenshotDelay?
scroll 在某一点上滚动内容——最适合滚动列表、网页、提要和主屏幕页面（触控板风格的滚动事件） x, y, direction?, distance?, screenshotDelay?
type_text 在焦点输入字段中键入文本。支持特殊按键： \b 退格， \t 选项卡， \x7f 正向删除， \x1b 逃跑 text, screenshotDelay?
press_button 按下设备按钮（主页、app_switch、聚光灯） button, screenshotDelay?

剪贴板

工具 说明 参数
get_clipboard 获取剪贴板文本（通用剪贴板） 无
set_clipboard 设置剪贴板文本（通用剪贴板） content, screenshotDelay?

实用

工具 说明 参数
get_coordinates 将网格标签转换为精确的像素坐标，以便点击/滑动/滚动 column, row, xPercent, yPercent

AI如何导航

与传统的自动化框架不同，没有 find_element 或可访问性树。AI使用 愿景：它截取屏幕截图，查看屏幕，然后点击它想要与之交互的坐标。这更简单、更稳健，并且与多模式AI代理的实际工作方式相匹配。

坐标网格叠加

原始的基于视觉的坐标估计是每个多模式代理的致命弱点——LLM在将“点击设置图标”转换为精确的像素坐标时是出了名的不精确。我们用一个 参考网格 在到达模型之前，它被合成到每个屏幕截图上。

┌──────────────────────────────────┐
│  margin    A     B     C     D   │  <- column labels (X axis)
│         ┌─────────────────────┐  │
│  A ─────│─ ─ ─ ─ ─ ─ ─ ─ ─ ─│  │  <- labeled reference lines
│         │                     │  │     at fixed intervals
│  B ─────│─ ─ ─ ─ ─ ─ ─ ─ ─ ─│  │
│         │    iPhone screen    │  │
│  C ─────│─ ─ ─ ─ ─ ─ ─ ─ ─ ─│  │
│         │                     │  │
│  D ─────│─ ─ ─ ─ ─ ─ ─ ─ ─ ─│  │
│         └─────────────────────┘  │
└──────────────────────────────────┘
   ^
   row labels (Y axis)

每个屏幕截图都被包裹在四周的深色边缘中 标记网格线 以固定的时间间隔。网格布局（间距、填充）是根据图像尺寸和配置的分割数动态计算的。MCP服务器指令告诉模型每个标签的确切像素值，给它一个可以直接从图像中读取的空间坐标系，而不是猜测。该模型识别最近的网格标签和调用 get_coordinates 通过百分比偏移来确定地获得精确的像素值。

结果：AI从“屏幕中间的某个地方”移动到“X轴上的网格线C和D之间，Y轴上的F线上”，并调用 get_coordinates 以计算精确的像素坐标。这实际上消除了对图标、按钮和文本字段等小目标的误点击。

事实证明，这是整个系统中最具影响力的部分之一。没有网格，基于视觉的代理会不断错过小点击目标——按钮、图标、文本字段都变成了猜谜游戏。网格为模型提供了一种可以精确推理的共享空间语言，将模糊的“粗略地点击这里”转化为确定性的坐标查找。这是一个简单的想法，但在实践中却产生了令人惊讶的巨大差异。

脚本

命令 描述
yarn build 与tsup捆绑 dist/
yarn start 运行已编译的服务器
yarn dev 在更改时自动重新启动运行
yarn doctor 飞行前检查（macOS、权限、设备）
yarn screenshot 使用网格覆盖捕捉iPhone屏幕，保存到 _screenshots/
yarn tap <x> <y> 点击屏幕截图坐标
yarn scroll <x> <y> [direction] [distance] 在一个点上滚动（方向：上/下/左/右，距离：像素，默认值：半屏幕尺寸）
yarn swipe <startX> <startY> <endX> <endY> 在两点之间滑动
yarn test 运行所有测试
yarn typecheck 不发射的类型检查
yarn lint ESLint棉绒
yarn format 带Prettier的格式
yarn check 格式+棉绒固定+字体检查

配置

通过环境变量进行配置（所有变量都以 IPHONE_MCP_):

变量 默认值 描述
IPHONE_MCP_LOG_LEVEL info 日志级别(debug, info, warn, error, silent)
IPHONE_MCP_SCREENSHOT_SCALE 1 屏幕截图分辨率倍数。更高的值会增加细节和令牌使用量
IPHONE_MCP_GRID_DIVISIONS 9 坐标叠加上的网格划分数。更多分割=更精细的精度
IPHONE_MCP_PNG_PALETTE true 为较小的屏幕截图启用基于调色板的PNG（256色）(true/false/1/0)
IPHONE_MCP_PNG_COMPRESSION_LEVEL 6 PNG zlib压缩级别，0-9（较高=文件较小但速度较慢）
IPHONE_MCP_MAX_PX_SINGLE_DIMENSION 1568 最长屏幕截图尺寸的最大像素数。防止LLM的图像过大
IPHONE_MCP_MOTION_STEP_INTERVAL_MS 50 滚动和滑动/拖动动画的步长间隔（ms）（最小1，最大10000）
IPHONE_MCP_LAUNCH_TIMEOUT_MS 10000 等待iPhone镜像启动的时间（毫秒）

故障排除

yarn doctor 失败

  • 从这里开始。它检查macOS版本、权限、USB连接等。

“未连接任何设备”

  • 检查iPhone是否已通过USB插入： system_profiler SPUSBDataType | grep -A5 iPhone
  • 确保在提示时点击iPhone上的“信任”

“iPhone镜像窗口未出现”

  • 请参阅Apple指南 设置iPhone镜像
  • 首先手动打开iPhone镜像(open -a "iPhone Mirroring")以确保其正常工作
  • 两台设备必须使用相同的Apple ID登录
  • 蓝牙和WiFi必须打开
  • iPhone必须锁定（如果手机解锁并正在使用中，iPhone镜像将无法连接）

屏幕截图为空白或错误

  • 服务器在启动时检查屏幕录制权限。如果缺少，请手动授予：
  • 系统设置>隐私和安全>屏幕录制-启用托管MCP服务器的应用程序（例如终端、VS代码、克劳德桌面）
  • 在授予屏幕录制权限后，您可能需要重新启动服务器

轻敲/滑动不起作用

  • 服务器在启动时提示输入辅助功能权限。如果您拒绝了它，请手动授予它：
  • 系统设置>隐私和安全>可访问性-启用托管MCP服务器的应用程序（例如终端、VS代码、克劳德桌面）

备注

  • 测试模型：此MCP服务器主要通过以下方式进行测试 克劳德·十四行诗4.5 和 克劳德作品4.6。它应该适用于支持MCP的其他多式联运模式，但您的里程可能会有所不同。
  • 滚动和滑动：基于手势的交互（滚动和滑动）可能很挑剔——它们需要经过macOS事件注入，但并不总是1:1映射到真实手指在玻璃上的行为。我们正在积极努力提高可靠性。如果滚动或滑动没有正确着陆，AI通常会自行重试或调整。

免责声明

该软件支持人工智能驱动的物理iPhone控制。通过使用它，您承认并同意：

  • 您全权负责 对于通过此工具执行的所有操作，无论是手动启动还是由AI代理自主启动。
  • 可能会发生意外行为 人工智能模型可能会误解屏幕内容，点击错误的目标，发送意外的消息，删除数据，进行购买，或在您的设备上执行其他不可逆的操作。作者不对任何此类结果负责。
  • 你承担所有风险 与授予对您的设备的自动化系统控制相关，包括但不限于数据丢失、意外通信、金融交易、隐私泄露和帐户修改。
  • 该软件不是为无监督使用而设计的 您应该监控所有AI启动的操作，并随时准备断开设备连接。
  • 请勿将此软件用于恶意目的，包括未经授权访问设备、监视、骚扰、欺诈或任何违反适用法律的活动。

对于因使用或误用本软件而导致的任何损害、损失或后果，作者不承担任何责任。使用风险自负。

许可证

麻省理工学院

相关 MCP