# MCP

将 Claude Code、Codex、Cursor 或任何 MCP 客户端连接到 Device MCP，让 AI Agent 在 iPhone 和 iPad 上查看、轻点、输入和测试。

Device MCP 将你的 AI 编程 Agent 连接到 iPhone 和 iPad 真机。Agent 可以查看屏幕、轻点和输入、打开 App、构建项目并在设备上测试，一切都在平常的对话中完成。

## 1. 什么是 Device MCP 的 MCP 服务器？
**MCP**（Model Context Protocol）是 AI Agent 与工具通信所用的开放标准。Device MCP 内置了 MCP 服务器，因此 Claude Code、Codex、Cursor 及其他兼容 MCP 的 Agent 都能像你一样操作设备。

服务器仅在你的 Mac 上运行。除了你让 Agent 查看的内容，屏幕画面和 App 都不会离开这台 Mac。请参阅[隐私与安全](../help/privacy-and-security.md)。

### ✅ 示例提示词
* 给我的 iPhone 截个图，告诉我屏幕上有什么。
* 打开“设置”，开启深色模式。
* 构建我的 App，在 iPad 上运行，检查登录页面能否正常使用。
* 用测试账号登录，往购物车里加一件商品，然后核对总价。
* 我的 App 在设备上崩溃了。找到崩溃报告并修复这个 Bug。
* 打开 `myapp://profile` 并截图。
* 录一段新手引导流程的视频。

## 2. 优势
| 优势 | 说明 |
| --- | --- |
| **在真机上测试** | Agent 在真实的 iPhone 或 iPad 上测试，拥有真实的性能、传感器和系统弹窗。 |
| **闭环开发** | 编辑、构建、运行、轻点、截图、修复：Agent 无需你介入即可检查自己的工作成果。 |
| **你看到的，它也看得到** | Agent 能读取屏幕上的文字和按钮，因此可以直接按名称轻点**登录**按钮。 |
| **一切由你掌控** | 有风险的操作会先询问你，每个操作都有记录，你随时可以接管。 |
| **适配你的 Agent** | 支持 Claude Code、Codex、Cursor 及其他任何 MCP 客户端。 |

## 3. 将 Device MCP 添加到你的 Agent
1. **打开 MCP 服务器**
   * 打开 **Device MCP → Settings → MCP**。
   * 打开 **Enable MCP Server**。
2. **复制对应 Agent 的配置**：在 **Settings → MCP → MCP Configuration** 中选择 **Claude Code**、**Codex** 或 **Manual**，然后点击 **Copy**。Inspector 的 **Agent** 标签页中也有相同的配置。
3. 按照下面的步骤**将配置添加到 Agent**。

### Claude Code
在“终端”中运行：

```bash
claude mcp add --scope user device-mcp -- "/Applications/Device MCP.app/Contents/MacOS/device-mcp"
```

`--scope user` 让 Device MCP 在所有项目中都可用。

### Codex
将以下内容添加到 `~/.codex/config.toml`：

```toml
[mcp_servers.device-mcp]
command = "/Applications/Device MCP.app/Contents/MacOS/device-mcp"
startup_timeout_sec = 30
tool_timeout_sec = 900
```

{% hint style="info" %}
构建 App 和等待你审批可能需要几分钟。`tool_timeout_sec` 能让 Codex 有足够的时间等待。
{% endhint %}

### Cursor 和其他 MCP 客户端
将以下内容添加到客户端的 MCP 设置中：

```json
{
  "mcpServers": {
    "device-mcp": {
      "command": "/Applications/Device MCP.app/Contents/MacOS/device-mcp",
      "args": []
    }
  }
}
```

4. **开始使用 Device MCP**
   * 保持 Device MCP 打开，并连接好设备。
   * 对 Agent 说，例如：“列出我的设备并截图。”

{% hint style="warning" %}
如果 Agent 提示 MCP 服务器已关闭，请打开 **Device MCP → Settings → MCP**，然后打开 **Enable MCP Server**。使用 Agent 需要 [Device MCP Pro](../license.md)。
{% endhint %}

## 4. Agent 能做什么
| 类别 | Agent 能做什么 |
| --- | --- |
| **设备** | 列出已连接的设备，选择其中一台并读取其详细信息。 |
| **查看屏幕** | 截图，并读取屏幕上的文字和按钮。 |
| **触控** | 轻点、轻点文字、轻点两下、长按、滑动、滚动和捏合。 |
| **输入** | 输入文本、按下按键和隐藏键盘。 |
| **系统** | 按下主屏幕、锁定、音量和 Siri 按钮，打开控制中心或 App 切换器，以及旋转屏幕。 |
| **App** | 列出、启动、退出、安装和卸载 App，以及打开链接。 |
| **Build & Run** | 构建 Xcode 项目并在设备上启动。请参阅 [Build & Run](build-and-run.md)。 |
| **调试** | 读取崩溃报告，下载 App 的数据。 |
| **录制** | 开始和停止录屏。 |
| **向你求助** | 请你介入，例如处理 Face ID 或密码。请参阅 [Human Handoff](human-handoff.md)。 |

MCP 客户端会显示当前 Device MCP 版本提供的完整工具列表。

## 5. 保持掌控
* **审批**：安装或移除 App、构建、打开链接和下载 App 数据前，都会先询问你。请参阅[操作审批](approvals.md)。
* **活动记录**：Agent 执行的每个操作都会列在 **Agent** 标签页中。请参阅 [Agent 活动](agent-activity.md)。
* **Agent is driving**：镜像画面底部的状态，以及边栏中设备旁的 ✨，会显示 Agent 何时在使用设备。
* **随时接管**：即使 Agent 正在工作，你的点击和按键也始终会生效。