📱 MCP Server for iOS Simulator

一个基于 appium-ios-simulator 并利用 MCP TypeScript SDK 实现的 Model Context Protocol (MCP) 服务器，用于 iOS 模拟器。

📋 概述

该项目提供了一个桥梁，连接 iOS 模拟器和 Model Context Protocol，允许与 iOS 模拟器实例进行标准化通信。它通过使用 MCP 协议实现了对 iOS 模拟器的程序化控制，并在不同环境中保持一致的接口。该服务器使用 stdio 作为传输机制，非常适合与 Claude Desktop 和其他兼容 MCP 的客户端集成。

🎬 演示

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

🏗️ 架构

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

1. 🔄 模拟器管理层 - 处理 iOS 模拟器的生命周期和交互
2. 🔌 MCP 协议实现 - 使用 TypeScript SDK 通过 stdio 传输实现 Model Context Protocol
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+

🔧 安装

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

# Install dependencies
npm install

⚙️ 配置

配置通过 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
   • 转到设置 > 高级
   • 在“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列出所有可用的模拟器：

      "Show me all available iOS simulators"
      

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

      "Boot the iOS simulator with UDID 5272EA61-5796-4372-86FE-3B33831D5CC1"
      

   3. 完成后，使用相同的UDID将其关闭：

      "Shut down the simulator with 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文件。

🙏 致谢

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