接入方式

接上你的 agent：MCP、HTTP API 与 skill

Mac 上的守护进程负责操作手机，对外提供三种入口：MCP server，给 Claude Code、Codex、 Claude Desktop、Cursor 等 MCP 客户端用；HTTP 接口，给 agent 和脚本用（/agent/*）； 网页和 iOS 原生 App，给人用。

安装脚本已经帮你做好的

装了 Claude Code、Codex 的话，安装时会自动给它们注册 MCP server；装了 Cursor、Claude Desktop 也会一并注册（IPHONE_USE_NO_CLIENT_SETUP=1 不动 Cursor 和 Claude Desktop）。agent skill 也会一起装好。如果当前对话里还没有 phone_* 工具，新开一个对话。

其他 MCP 客户端

只要填命令，在这台 Mac 上 server 会自己找到守护进程和令牌。填绝对路径（替换 你的用户名），把这一项合并进文件，保留里面已有的 server。

json · mcpServers

{
  "mcpServers": {
    "iphone-use": {
      "command": "/Users/你的用户名/Applications/iPhoneUse.app/Contents/MacOS/iphone-use-mcp"
    }
  }
}

客户端	配置文件	写法
Cursor	`~/.cursor/mcp.json`（或项目里的 `.cursor/mcp.json`）	上面的 `mcpServers` 写法
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json`	上面的 `mcpServers` 写法；改完退出再重开 App
Gemini CLI	`~/.gemini/settings.json`（或项目里的 `.gemini/settings.json`）	上面的 `mcpServers` 写法
Windsurf / Devin Desktop	`~/.codeium/windsurf/mcp_config.json`（新版本是 `~/.config/devin/mcp_config.json`）	上面的 `mcpServers` 写法
VS Code / Copilot	工作区里的 `.vscode/mcp.json`，或用 MCP: Open User Configuration	键名是 `servers`，`"type": "stdio"`
opencode	`~/.config/opencode/opencode.json`（或项目里的 `opencode.json`）	键名是 `mcp`，命令写成数组

json · VS Code

{
  "servers": {
    "iphone-use": {
      "type": "stdio",
      "command": "/Users/你的用户名/Applications/iPhoneUse.app/Contents/MacOS/iphone-use-mcp"
    }
  }
}

json · opencode

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "iphone-use": {
      "type": "local",
      "command": ["/Users/你的用户名/Applications/iPhoneUse.app/Contents/MacOS/iphone-use-mcp"],
      "enabled": true
    }
  }
}

它在 MCP 注册表中的名字（见仓库里的 server.json）是 io.github.leeguooooo/iphone-use。

Codex 和 Claude Code 插件

插件带 skill 和 MCP server，但仍需先完成安装。

Codex · Claude Code

$ codex plugin marketplace add leeguooooo/iphone-use && codex plugin add iphone-use@iphone-use
# 在 Claude Code 里
> /plugin marketplace add leeguooooo/iphone-use
> /plugin install iphone-use@iphone-use

MCP 工具

分组	工具
看	`phone_status`、`phone_capabilities`、`phone_screenshot`、`phone_elements`（带一个 `registry` 块，列出当前 App 已安装的 flow）
操作	`phone_tap`、`phone_tap_element`（绑定快照）、`phone_tap_label`（唯一的精确标签）、`phone_scroll`、`phone_type`、`phone_key`、`phone_shortcut`
批量	`phone_run_steps`（最多 24 步，可加 `wait_for`）、`phone_jev_run`（把整个目标交给手机上的快速 agent）
生命周期	`phone_reconnect`、`phone_hold`、`phone_release_owner`、`phone_login`（在守护进程内用你自己的密码库登录 App）
Flow	`phone_flow_list`、`phone_flow_info`、`phone_flow_run`、`phone_flow_draft`、`phone_flow_update`、`phone_flow_publish`、`phone_flow_report`
统计	`phone_run_start`、`phone_run_end`
开发测试	`phone_logs`、`phone_crashes`、`phone_record`、`phone_install_app`、`phone_set_location`、`phone_app_notes`

完整参数见 crates/mcp/README.md。

怎么读结果

文本块写给模型看，很紧凑：操作后稳定下来的变化、每个元素一行，或者一个批次的结论和结束时的画面。
structuredContent 默认精简，只放程序要判断的字段（ok、outcome、retry_safe、error、failed_step、snapshot 等）。IPHONE_USE_MCP_STRUCTURED=full 发送守护进程的完整 JSON，off 不发送。
结果无法确认时，返回 outcome: "unknown" 和 retry_safe: false。只看 retry_safe 决定能否重试，不要看 outcome：先读屏，再决定下一步。

收窄工具、走 HTTP、选手机

IPHONE_USE_MCP_TOOLS=readonly 只开放读取类工具；写一个逗号分隔的列表则只开放列出的工具。
iphone-use-mcp --listen 127.0.0.1:端口 可以通过 HTTP 提供 MCP。监听 127.0.0.1 时只有本机能连；其他机器上的客户端要通过带认证的隧道访问，或者监听其他地址并设置 IPHONE_USE_MCP_TOKEN（非回环地址必须设置）。
装了多台手机时，phone_instances 只读列出实例，不重连；每次调用都可以用 instance:"i13" 选一台。省略参数仍使用启动时配置的守护进程，实例缺失时直接报错，不改选其他手机。
手边没有手机？iphone-use simulator start "iPhone 16 Pro"，再用 claude mcp add iphone-sim -e IPHONE_USE_INSTANCE=sim -- iphone-use-mcp 接上（预览功能，需要 Xcode）。

HTTP 接口

请求头	什么时候带	作用
`Authorization: Bearer <token>`	每个 `/agent/*` 请求	设置了 `IPHONE_USE_AGENT_TOKEN` 就用它，否则用守护进程密码
`X-Phone-Control: 1`	每个会改变状态的 POST	在鉴权之上再确认一次意图，不能代替鉴权
`X-Phone-Owner: <会话名>`	控制类请求	为这个会话占用手机；租约有效期间其他会话会收到 `409 phone_owned`

接口	用途
`GET /agent/status`	就绪状态和生命周期；`drivable:true` 时才操作，否则报告 `hint`
`GET /agent/elements`	屏幕的扁平无障碍树，附一个 `snapshot` 令牌
`GET /agent/screenshot`	屏幕 PNG；禁止截屏的页面返回带标签的线框图
`POST /agent/input`	一个操作（点击、输入、滚动、`launch_app`、`set_value` 等）；加 `?return=delta` 一并返回界面变化
`POST /agent/actions`	最多 24 步整体校验，遇到第一个失败就停，并给出整批的 `retry_safe`
`POST /agent/mode`	`agent` 启动 runner；`human` 把手机交还给拿着它的人

bash

$ AUTH="Authorization: Bearer $TOKEN"; CTL="X-Phone-Control: 1"
$ curl -s -H "$AUTH" $HOST/agent/elements                     # 屏幕读成文字，附一个快照令牌
$ curl -s -H "$AUTH" -H "$CTL" -X POST "$HOST/agent/input?return=delta" \
    -d '{"type":"tap","element":7,"snapshot":"…"}'            # 点击，并返回界面变化

守护进程默认监听 127.0.0.1:44321。完整参考见 Agent API。

skill

安装脚本把 skill 装在 ~/.agents/skills/iphone-use，并为 Claude Code 建好发现链接。它教 agent 按这个循环操作：

先探测：phone_status；读屏和输入都要求 drivable:true，否则报告 hint 并停下。只有当前任务确实需要手机时才重连一次。
先找现成的 flow：registry 块里有能完成任务的，就用 phone_flow_run 跑。
成批操作，不要一下一下点：读一次屏，把已经知道怎么做的步骤合成一个 phone_run_steps 批次发出去，每次换屏后加 wait_for。
逐步验证：ok:true 只说明发出去了，不说明达到了目的。
问要不要存成 flow，做完后用 phone_release_owner 释放手机。

📱 让 agent 用手机

示例说法，以及 agent 能在手机上做什么。

⚙️ 它怎么工作

守护进程、XCTest runner、USB 与 Wi-Fi。