iphone-mcp

🚀 iPhone MCP Server

iPhone MCP Server 是一个基于 Appium 实现 iPhone 任务自动化的模型上下文协议（MCP）服务器。它支持通过可流式传输的 HTTP 协议进行应用控制、UI 交互和屏幕截图捕获。

我们推荐使用 Cherry Studio 作为 iPhone 自动化的 MCP 客户端。

🚀 快速开始

运行 ./start.sh 启动 Appium 和 MCP 服务器。在默认设置下，可通过 http://127.0.0.1:8765/mcp 访问。

✨ 主要特性

• 获取设备信息并列出已安装的应用
• 捕获屏幕截图（JPEG 格式，约 500KB）
• 列出 UI 元素并执行触摸操作
• 使用应用包 ID 启动或切换应用
• 优化 XML 输出以减少令牌使用

📦 安装指南

前提条件

• Python 3.8 或更高版本
• Node.js 和 npm
• 带有 UDID 的 iPhone
• Xcode

步骤

1. 克隆仓库：git clone https://github.com/Lakr233/iphone-mcp.git && cd iphone-mcp
2. 设置虚拟环境：python -m venv .venv && source .venv/bin/activate
3. 安装依赖项：pip install -r requirements.txt
4. 安装 Appium：npm install -g appium && appium driver install xcuitest
5. 设置 WebDriver Agent：请遵循 WebDriver Agent 指南
6. 配置：在 start.sh 中编辑 DEVICE_UDID

💻 使用示例

基础用法

以下是启动服务器的基本命令：

./start.sh

高级用法

可以使用以下工具完成不同的任务：

• iphone_device_info：获取设备详细信息
• iphone_device_apps：列出已安装的应用
• iphone_interface_snapshot：捕获屏幕截图和 XML
• iphone_interface_elements：列出 UI 元素
• iphone_operate_click：执行点击操作
• iphone_operate_swipe：执行滑动操作
• iphone_operate_text_input：输入文本
• iphone_operate_app_launch：启动应用
• iphone_operate_get_current_bundle_id：获取当前应用的包 ID

📚 详细文档

配置

在 start.sh 中设置环境变量（默认值在 src/utils.py 中）： | 属性 | 详情 | |------|------| | DEVICE_UDID | 必需的设备 UDID | | APPIUM_HOST/PORT | Appium 的主机和端口 | | SERVER_HOST/PORT/PATH | 服务器的主机、端口和路径 | | LOG_LEVEL | 日志级别 |

开发

• 运行测试：pytest
• 代码风格：Python 3.8+ 并使用类型提示

贡献

您可以 Fork 仓库，创建分支并提交拉取请求。通过 Issues 报告错误或提出功能建议。

📄 许可证

本项目采用 MIT 许可证。