本文将深入介绍一款基于 Appium 构建的 iOS 设备自动化测试 MCP Server。该工具支持屏幕截图、元素点击与 UI 树获取，能够无缝集成 Trae 等支持 MCP 协议的 AI 客户端。对于需要高效实现 iOS 自动化操作的用户而言，这是一个非常实用的解决方案。
安装依赖
项目采用 uv 进行依赖管理，流程十分简洁。只需运行以下命令即可完成全部依赖的安装：
uv sync
运行方式
方式一：Stdio 模式（推荐用于 Trae）
该模式是与 Trae 这类 AI 客户端集成的最佳选择。在终端中执行：
uv run python mcp_server.py --stdio
方式二：SSE 模式（用于远程连接）
如需远程访问或与其他支持 SSE 的服务集成，使用默认启动方式即可：
uv run python mcp_server.py
启动后，服务器默认运行在 https://localhost:8000。
Trae MCP 配置
Stdio 模式（推荐）
在 Trae 的 MCP Servers 配置中，直接添加以下 JSON 配置即可完成集成：
{
"name": "iOS Screenshot MCP",
"type": "stdio",
"command": "uv run python mcp_server.py --stdio",
"cwd": "~/mcp-servers/ios-playwright-mcp",
"enabled": true
}
SSE 模式
首先确保服务器已启动：
cd ~/mcp-servers/ios-playwright-mcp
uv run python mcp_server.py
然后在 Trae 中添加以下配置：
{
"name": "iOS Screenshot MCP",
"type": "sse",
"url": "https://localhost:8000/mcp/sse",
"enabled": true
}
Claude code MCP 配置
对于使用 Claude code 的用户，配置方法如下：
{
"mcpServers": {
"ios-playwright": {
"name": "ios-playwright",
"type": "stdio",
"command": "bash",
"args": ["-c", "source ~/mcp-servers/ios-playwright-mcp/.venv/bin/activate && uv run python ~/mcp-servers/ios-playwright-mcp/mcp_server.py --stdio"],
"cwd": "~/mcp-servers/ios-playwright-mcp/"
}
}
}
工具说明
这个 MCP Server 提供了三个核心工具，能够覆盖自动化测试中的常见场景，满足 iOS 设备操作需求。
take_ios_screenshot_tool
截取 iOS 设备当前屏幕并保存为图片文件。参数如下：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| platform_name | str | iOS | 平台名称 |
| automation_name | str | XCUITest | 自动化框架名称 |
| device_name | str | iPhone 16 Pro Max | 设备名称 |
| udid | str | 32EFED52-E30A-4CC8-AAE9-525B5A3A5B6A | 设备唯一标识符 |
| bundle_id | str | com.xue.Demo01 | 应用 Bundle ID |
| appium_server_url | str | https://127.0.0.1:4723 | Appium 服务器地址 |
| output_path | str | screen.png | 截图保存路径 |
返回值是截图文件的完整路径。
element_click_tool
通过 accessibility_id 点击 iOS 设备上的元素。参数如下：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| accessibility_id | str | - | 元素的 accessibility identifier（必填项） |
| platform_name | str | iOS | 平台名称 |
| automation_name | str | XCUITest | 自动化框架名称 |
| device_name | str | iPhone 16 Pro Max | 设备名称 |
| udid | str | 32EFED52-E30A-4CC8-AAE9-525B5A3A5B6A | 设备唯一标识符 |
| bundle_id | str | com.xue.Demo01 | 应用 Bundle ID |
| appium_server_url | str | https://127.0.0.1:4723 | Appium 服务器地址 |
返回值是操作结果消息。
dump_ui_element_tool
获取 iOS 设备当前屏幕的完整 UI 元素树，以 XML 格式返回。参数如下：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| platform_name | str | iOS | 平台名称 |
| automation_name | str | XCUITest | 自动化框架名称 |
| device_name | str | iPhone 16 Pro Max | 设备名称 |
| udid | str | 32EFED52-E30A-4CC8-AAE9-525B5A3A5B6A | 设备唯一标识符 |
| bundle_id | str | com.xue.Demo01 | 应用 Bundle ID |
| appium_server_url | str | https://127.0.0.1:4723 | Appium 服务器地址 |
返回值是 UI 元素树的 XML 字符串。
前置条件
在实际调用截图工具之前，需要确保以下基础条件已经满足：
- Appium Server 已经启动，地址为
https://127.0.0.1:4723 - 目标设备或模拟器已经成功连接
- 需要测试的应用（通过
bundle_id指定）已经安装在设备上
这些都是常规操作步骤，但缺失任何一个都会导致调用失败。
文件结构
项目结构清晰明了，核心文件如下：
.
├── mcp_server.py # MCP Server 主文件
├── screenshot_service.py # Appium 服务模块（会话管理、截图、点击、UI树）
├── main.py # 原始截图脚本
├── pyproject.toml # 项目配置
└── README.md # 项目说明
会话管理
值得一提的是，所有工具共享同一个 Appium 会话，这意味着不会重复建立连接。会话在首次调用任一工具时自动创建，并保持活跃状态直到服务器停止。这种设计有效减少了连接开销，显著提升了整体执行效率。
