📱 MCP Server for iOS Simulator

📱 iOS 模拟器的 MCP 服务

一个为 iOS 模拟器实现 Model Context Protocol（MCP）的服务，基于 appium-ios-simulator 构建，并使用 MCP TypeScript SDK。

📋 概述

本项目为 iOS 模拟器与 Model Context Protocol 提供桥接，使其能够与 iOS 模拟器实例进行标准化通信。它支持以编程方式控制 iOS 模拟器，同时利用 MCP 协议在不同环境中提供一致的接口。该服务使用 stdio 作为传输机制，非常适合与 Claude Desktop 和其他兼容 MCP 的客户端集成。

🎬 演示

演示如何使用 Claude AI Desktop 启动 iOS 模拟器

🏗️ 架构

该服务由三个主要组件组成：

1. 🔄 模拟器管理层 - 处理 iOS 模拟器的生命周期和交互
2. 🔌 MCP 协议实现 - 使用 TypeScript SDK 实现 Model Context Protocol，并采用 stdio 传输
3. 📊 日志记录组件 - 提供基于文件的日志记录，且不会干扰 stdio 传输

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  MCP Protocol   │     │     Stdio       │     │    Simulator    │
│  Implementation │◄────┤    Transport    │◄────┤   Management    │
│                 │     │                 │     │      Layer      │
└─────────────────┘     └─────────────────┘     └─────────────────┘
        ▲                                                ▲
        │                                                │
        ▼                                                ▼
┌─────────────────┐                             ┌─────────────────┐
│   MCP Client    │                             │  iOS Simulator  │
│  (e.g. Claude)  │                             │                 │
└─────────────────┘                             └─────────────────┘

✨ 功能

• 🚀 启动、停止和管理 iOS 模拟器实例
• 🔌 启动和关闭模拟器
• 📲 在模拟器上安装和启动应用
• 📸 截取模拟器屏幕
• 👆 在指定坐标执行点击
• 🔄 支持多个模拟器会话并发运行
• 📝 全面的基于文件的日志记录，不输出到控制台
• 🛡️ 具备错误恢复能力

📋 前提条件

• 🟢 Node.js（v16 或更高版本）
• 🍎 macOS（iOS 模拟器必需）
• 🛠️ 已安装 iOS 模拟器的 Xcode
• 📜 TypeScript 4.5+

🔧 安装

通过 Smithery 安装

通过 Smithery 为 Claude Desktop 自动安装 iOS Simulator Control Server：

npx -y @smithery/cli install @atom2ueki/mcp-server-ios-simulator --client claude

手动安装

# Clone the repository
git clone https://github.com/atom2ueki/mcp-server-ios-simulator.git
cd mcp-server-ios-simulator

# Install dependencies
npm install

🐳 Docker

提供了 Dockerfile，可将该服务打包，用于 Glama MCP 目录及其他容器托管平台。

docker build -t mcp-server-ios-simulator .
docker run --rm -i mcp-server-ios-simulator

注意： iOS 模拟器只能在 macOS 上运行，因此 Linux 容器可以托管 MCP 进程并通过 stdio 响应，但无法驱动真实的模拟器。该容器旨在用于可移植性检查，以及桥接到 macOS 主机的远程 MCP 环境。

⚙️ 配置

通过 src/config.ts 文件进行配置：

const config = {
  simulator: {
    defaultDevice: process.env.SIMULATOR_DEFAULT_DEVICE || 'iPhone 16',
    defaultOS: process.env.SIMULATOR_DEFAULT_OS || '18.2',
    timeout: parseInt(process.env.SIMULATOR_TIMEOUT || '30000', 10),
  }
};

你可以通过设置环境变量自定义这些设置：

SIMULATOR_DEFAULT_DEVICE=iPhone 16
SIMULATOR_DEFAULT_OS=18.2
SIMULATOR_TIMEOUT=30000

🚀 使用方法

🔨 构建和启动服务

# Build the project
npm run build

# Start the server
npm start

🧰 MCP 工具

该服务提供两种不同的 iOS 模拟器控制方式：

📱 直接管理模拟器（推荐）

这些工具直接使用模拟器 UDID，无需维护会话：

• 📋 list-available-simulators - 列出所有可用模拟器及其 UDID
• ▶️ boot-simulator-by-udid - 直接使用 UDID 启动模拟器
• ⏹️ shutdown-simulator-by-udid - 直接使用 UDID 关闭模拟器
• 📊 list-booted-simulators - 列出所有当前已启动的模拟器

适用场景： 只需直接启动、使用和关闭模拟器时。

📱 基于会话的管理（高级）

这些工具使用会话层，通过自定义会话 ID 跟踪模拟器：

• 📋 list-simulator-sessions - 列出所有活动的模拟器会话
• ➕ create-simulator-session - 创建新的模拟器会话
• ❌ terminate-simulator-session - 终止会话（关闭模拟器并清理）
• 🔄 create-and-boot-simulator - 创建新的模拟器会话并启动模拟器
• ▶️ boot-simulator - 为现有会话启动模拟器
• ⏹️ shutdown-simulator - 为现有会话关闭模拟器

适用场景： 需要跟踪模拟器元数据、使用自定义 ID 引用模拟器，或使用更高级的管理功能时。

📲 应用管理

• 📥 install-app - 在模拟器上安装应用
• 🚀 launch-app - 在模拟器上启动应用
• 🛑 terminate-app - 终止正在运行的应用

🖱️ 交互工具

• 📷 take-screenshot - 截取模拟器屏幕
• 👆 tap-coordinate - 在指定坐标处点击

🤖 使用 Claude Desktop 的示例

1. 配置 Claude Desktop，将此服务作为 MCP 工具使用：

   • 打开 Claude Desktop
   • 前往 Settings > Advanced
   • 在 "MCP Servers" 部分添加以下配置：

   {
     "mcpServers": {
       "simulator": {
         "command": "node",
         "args": [
           "/path/to/your/mcp-server-ios-simulator/dist/index.js"
         ]
       }
     }
   }
   

   • 将 /path/to/your 替换为此仓库的实际安装路径
   • 保存设置并重启 Claude Desktop

2. 使用提供的工具，直接通过 Claude Desktop 控制 iOS 模拟器：

   直接使用 UDID（推荐）：

   1. 首先，让 Claude 列出可用的模拟器：

      "显示所有可用的 iOS 模拟器"
      

   2. 然后使用 UDID 启动指定的模拟器：

      "启动 UDID 为 5272EA61-5796-4372-86FE-3B33831D5CC1 的 iOS 模拟器"
      

   3. 完成后，使用相同的 UDID 关闭模拟器：

      "关闭 UDID 为 5272EA61-5796-4372-86FE-3B33831D5CC1 的模拟器"
      

   对于大多数使用场景，直接使用 UDID 的方式更简单、更可靠。

   基于会话的方式（高级）： 只有在需要会话跟踪的高级功能时，才使用此方式：

   "Create a new simulator session for iPhone 16 Pro with iOS 18.2"
   "Boot the simulator for session abc-123"
   "Take a screenshot of the simulator for session abc-123"
   "Terminate the simulator session abc-123"
   

👨‍💻 开发

📁 项目结构

src/
├── simulator/       # Simulator management layer
├── mcp/             # MCP protocol implementation
├── bridge/          # Bridge component
├── utils/           # Utility functions including logger
├── config.ts        # Configuration handling
└── index.ts         # Entry point

🔨 构建项目

# Install development dependencies
npm install

# Run TypeScript compiler
npm run build

📜 许可证

本项目采用 MIT License 授权，详情请参阅 LICENSE 文件。

🙏 致谢

• 📱 appium-ios-simulator 提供了 iOS 模拟器交互功能
• 🔌 Model Context Protocol 提供了协议规范和 TypeScript SDK