📱 MCP Server for iOS Simulator

📱 iOS 模拟器 MCP 服务

一个 Model Context Protocol (MCP) 服务，可让大模型通过自然语言命令与 iOS 模拟器交互。

ℹ️ 概览

此 MCP 服务为大语言模型 (LLM) 与 iOS 模拟器搭建了桥梁，可通过自然语言命令进行全面控制。它可以执行以下操作：

如需详细用法，请参阅安装指南和支持的命令部分。你可以通过直接集成 MCP 或将其用作独立库来使用此服务。

查看架构部分，了解各组件如何协同工作，以实现通过自然语言控制 iOS 模拟器。如需了解完整的执行流程、组件契约和会话模型，请参阅 ARCHITECTURE.md。有关在此代码库中工作的 Agent 和贡献者的指南，请参阅 AGENTS.md。

🎮 模拟器控制

• 创建和管理模拟器会话
• 启动、关闭模拟器并监控其状态
• 列出可用和正在运行的模拟器
• 聚焦模拟器窗口

📱 应用管理

• 安装和管理 iOS 应用
• 启动、终止和卸载应用
• 监控应用状态并验证安装
• 处理应用权限和配置

🖱️ UI 交互与测试

• 与模拟器 UI 交互
• 执行点击、滑动和按键操作
• 输入文本和按键序列
• 访问无障碍元素以进行 UI 测试
• 录制 UI 交互视频

🛠️ 开发与调试

• 截取屏幕截图并获取系统日志
• 实时调试应用
• 监控和分析崩溃日志
• 安装动态库并管理应用数据

⚡ 高级功能

• 其他功能包括：
  • 位置模拟
  • 媒体注入
  • URL 方案处理
  • 联系人数据库管理
  • 钥匙串操作

如需详细用法，请参阅安装指南和支持的命令部分。你可以通过直接集成 MCP 或将其用作独立库来使用此服务。

查看架构部分，了解各组件如何协同工作，以实现通过自然语言控制 iOS 模拟器。

📋 要求

• macOS：iOS 模拟器支持所必需
• Node.js：v20.0.0 或更高版本
• Homebrew：安装依赖项所必需
• XCode：已安装 iOS 模拟器

🚀 安装

通过 Cline 安装此服务最简单：

1. 直接向 Cline 提出请求：

Add this mcp to cline https://github.com/InditexTech/mcp-server-simulator-ios-idb

2. Cline 将自动处理安装流程，包括依赖项管理和配置。

或者，你也可以手动安装：

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

# Create and activate Python virtual environment
python3 -m venv venv
source venv/bin/activate  # On Unix/macOS

# Install dependencies
npm install

# Build the project
npm run build

# Start the project
npm start

# Run tests
npm test

安装流程将自动：

1. 检查你是否正在使用 macOS
2. 通过 Homebrew 安装 idb-companion
3. 在虚拟环境中通过 pip 安装 fb-idb

注意：使用此服务时，请确保虚拟环境保持激活状态。如果关闭终端后再回来，需要在运行 npm start 前使用 source venv/bin/activate 命令重新激活虚拟环境。

🔌 MCP 集成

要将此服务与 Claude 或其他 LLM 助手配合使用：

1. 将服务添加到 Claude Desktop 的 MCP 设置中：

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

2. 现在，大模型可以使用自然语言命令控制 iOS 模拟器：

create a simulator session with iPhone 14
install app /path/to/my-app.ipa
launch app com.example.myapp
tap at 100, 200
take a screenshot

📚 作为库使用

你也可以在自己的项目中将此软件包用作库：

🔰 基本用法

⚠️ 导入副作用：导入包入口点 （'mcp-server-simulator-ios-idb' / dist/index.js）会在模块加载时运行服务器启动 代码：覆盖控制台输出、创建 logs/ 目录、注册 SIGINT/SIGTERM/异常处理程序，并且无条件启动 MCP stdio 服务。目前无法选择禁用。对包根目录的任何导入都适用——使用命名导入也无法跳过 引导代码。若要在不触发传输和信号副作用的情况下使用解析器／编排器／管理器，请像下方所示，通过深层 路径导入已编译的组件模块（dist/...）；请注意，导入 dist/mcp/mcp-server.js 也会引导 MCP 服务单例，因此用于库时请避免此路径。该包仅声明了 "main"（没有 exports 映射），因此深层路径可以正常解析。

// Deep imports of compiled component modules: these do NOT trigger the
// package root startup (no MCP stdio server, no signal handlers).
import { MCPOrchestrator } from 'mcp-server-simulator-ios-idb/dist/orchestrator/MCPOrchestrator.js';
import { NLParser } from 'mcp-server-simulator-ios-idb/dist/parser/NLParser.js';
import { IDBManager } from 'mcp-server-simulator-ios-idb/dist/idb/IDBManager.js';

async function main() {
  // Compose the components (equivalent to createMCPServer internals)
  const idbManager = new IDBManager();
  const parser = new NLParser();
  const orchestrator = new MCPOrchestrator(parser, idbManager);

  // Process natural language commands

  // Create a simulator session
  const sessionResult = await orchestrator.processInstruction('create session');
  console.log(`Session created: ${sessionResult.data}`);

  // Interact with the simulator
  await orchestrator.processInstruction('tap at 100, 200');

  // Capture a screenshot
  const screenshotResult = await orchestrator.processInstruction('take screenshot');
  console.log(`Screenshot saved at: ${screenshotResult.data}`);
}

main().catch(console.error);

ℹ️ MCP 服务本身（目前定义于 src/mcp/mcp-server.ts，未从包入口点重新导出）只有在通过 npm start / MCP 客户端配置运行实际服务进程时才有意义；其 createMCPServer() 工厂只是组合上方展示的三个组件。

🚀 进阶用法

你也可以通过深层导入直接使用各个组件：

import { IDBManager } from 'mcp-server-simulator-ios-idb/dist/idb/IDBManager.js';

// Create instance and use it directly
const idbManager = new IDBManager();

const sessionId = await idbManager.createSimulatorSession({
  deviceName: 'iPhone 12',
  platformVersion: '15.0'
});

await idbManager.tap(sessionId, 100, 200);

🏗️ 项目结构

mcp-server-simulator-ios-idb/
├── src/                      # Source code
│   ├── adapters/             # Adapter components
│   ├── idb/                  # IDB manager implementation
│   ├── mcp/                  # MCP server implementation
│   ├── orchestrator/         # Command orchestrator
│   ├── parser/              # Natural language parser
│   └── index.ts             # Main entry point
├── scripts/                 # Installation scripts
├── package.json            # Project configuration
└── tsconfig.json          # TypeScript configuration

🎯 支持的命令

NLParser 支持以下自然语言命令：

🎮 模拟器管理

命令	描述	示例
创建会话	创建新的模拟器会话	"create session", "create simulator iPhone 12"
终止会话	终止当前会话	"terminate session", "close simulator"
列出模拟器	列出可用的模拟器	"list simulators", "show simulators"
列出已启动的模拟器	列出正在运行的模拟器	"list booted simulators", "show running simulators"
启动模拟器	根据 UDID 启动模拟器	"boot simulator 5A321B8F-4D85-4267-9F79-2F5C91D142C2"
关闭模拟器	关闭模拟器	"shutdown simulator 5A321B8F-4D85-4267-9F79-2F5C91D142C2"
聚焦模拟器	将模拟器窗口置于前台	"focus simulator", "bring simulator to front"
列出模拟器会话	列出活动的模拟器会话	"list simulator sessions", "show active sessions"

📱 应用管理

命令	描述	示例
安装应用	在模拟器上安装应用	"install app /path/to/app.ipa"
启动应用	在模拟器上启动应用	"launch app com.example.app"
终止应用	终止正在运行的应用	"terminate app com.example.app"
卸载应用	卸载应用	"uninstall app com.example.app"
列出应用	列出已安装的应用	"list apps", "show installed apps"
检查应用是否已安装	检查应用是否已安装	"is app com.example.app installed"

🖱️ UI 交互

命令	描述	示例
点击	在指定坐标处点击	"tap at 100, 200"
滑动	执行滑动手势	"swipe from 100, 200 to 300, 400"
按下按钮	按下设备按钮	"press button HOME", "press button SIRI"
输入文本	输入文本	"input text Hello World"
按键	根据代码按下按键	"press key 4"
按键序列	按下按键序列	"press key sequence 4 5 6"

♿ 无障碍功能

命令	描述	示例
描述元素	列出所有无障碍元素（尚未实现）	"describe all elements", "show accessibility elements"
描述坐标点	描述指定坐标处的元素（尚未实现）	"describe point 100, 200", "what's at 150, 300"

📸 捕获和日志

命令	描述	示例
截取屏幕截图	截取屏幕截图	"take screenshot", "capture screen"
录制视频	录制屏幕活动（尚未实现）	"record video /path/output.mp4"
停止录制	停止视频录制（尚未实现）	"stop recording", "stop video recording"
获取日志	获取系统或应用日志	"get logs", "get logs for com.example.app"

🐛 调试

命令	描述	示例
开始调试	启动调试会话（尚未实现）	"debug app com.example.app", "start debug com.example.app"
停止调试	停止调试会话（尚未实现）	"stop debug", "terminate debug session"
调试状态	获取调试会话状态	"debug status", "show debug info"

💥 崩溃日志

命令	描述	示例
列出崩溃日志	列出可用的崩溃日志	"list crash logs", "show crash logs"
显示崩溃日志	显示崩溃日志的内容	"show crash log crash_2023-01-01"
删除崩溃日志	删除某个应用的崩溃日志；明确要求时可删除全部日志	"delete crash logs for com.example.app", "delete all crash logs"

🔧 其他命令

命令	描述	示例
安装 dylib	安装动态库	"install dylib /path/to/library.dylib"
打开 URL	在模拟器中打开 URL	"open url https://example.com"
清除钥匙串	清除模拟器的钥匙串	"clear keychain"
设置位置	设置模拟器的位置	"set location 37.7749, -122.4194"
添加媒体	将媒体添加到相机胶卷	"add media /path/to/image.jpg"
授予权限	授予应用权限	"approve permissions com.example.app photos camera"
更新联系人	更新联系人数据库	"update contacts /path/to/contacts.sqlite"

该接口支持 idb CLI 工具提供的所有命令，为 iOS 模拟器自动化提供全面的操作集。

🔍 架构

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

1. IDBManager：直接通过 idb 与 iOS 模拟器交互的底层组件。
2. NLParser：解释自然语言指令并将其转换为结构化命令的组件。
3. MCPOrchestrator：协调解析器与 IDBManager 之间交互的中央组件。

这些组件通过适配器连接：

• ParserToOrchestrator：将解析器结果转换为编排器命令。
• OrchestratorToIDB：将编排器命令转换为 IDBManager 调用。

完整的执行流程（MCP stdio → 编排器 → 解析器/注册表 → 适配器 → IDBManager → idb / xcrun simctl）、组件契约、会话模型（activeSessionId 与 sessionId → UDID）以及添加新命令的检查清单，均记录在 ARCHITECTURE.md 中。

🔌 MCP 集成

要将此服务与 Model Context Protocol 配合使用：

1. 将服务添加到 MCP 设置中：

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

2. 在 LLM 应用中连接到该服务：

const result = await useMcpTool({
  serverName: "ios-simulator",
  toolName: "process-instruction",
  arguments: {
    instruction: "create simulator session"
  }
});

🙏 致谢

本项目的实现离不开 facebook/idb，它提供了底层的 iOS 模拟器控制能力。我们衷心感谢 Facebook/Meta 团队以及 idb 项目的所有贡献者，感谢他们创建并维护了如此强大且可靠的工具。

📄 许可证

此工具依据 Apache-2.0 条款以开源形式提供。