iOS PlayWright mcp server

今天要聊的是一个基于 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

启动后，服务器默认运行在 http://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": "http://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 提供了三个核心工具，基本覆盖了自动化测试的常见场景。

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	http://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	http://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	http://127.0.0.1:4723	Appium 服务器地址

返回值是 UI 元素树的 XML 字符串。

前置条件

在实际调用截图工具之前，需要确保几个基础条件已经满足：

1. Appium Server 已经启动，地址为 http://127.0.0.1:4723
2. 目标设备或模拟器已经成功连接
3. 需要测试的应用（通过 bundle_id 指定）已经安装在设备上

这些都是常规操作，但缺失任何一个都会导致调用失败。

文件结构

项目结构非常清晰，核心文件如下：

.
├── mcp_server.py # MCP Server 主文件
├── screenshot_service.py # Appium 服务模块（会话管理、截图、点击、UI树）
├── main.py # 原始截图脚本
├── pyproject.toml # 项目配置
└── README.md # 项目说明

会话管理

值得一提的是，所有工具共享同一个 Appium 会话，这意味着不会重复建立连接。会话在首次调用任一工具时自动创建，并保持活跃状态直到服务器停止。这种设计减少了连接开销，提升了整体效率。