npm package: @iflow-mcp/mcp-server-simulator-ios-idb
Description: Model Context Protocol server for iOS simulator automation via IDB
Author: arturono[at]inditex[dot]com
Latest version: 1.0.1

# 📱 MCP Server for iOS Simulator

[![MCP Server](https://glama.ai/mcp/servers/@InditexTech/mcp-server-simulator-ios-idb/badge)](https://glama.ai/mcp/servers/@InditexTech/mcp-server-simulator-ios-idb)

A Model Context Protocol (MCP) server that enables LLMs to interact with iOS simulators through natural language commands.

## ℹ️ Overview

This MCP server provides a bridge between Large Language Models (LLMs) and iOS simulators, offering comprehensive control through natural language commands. Here's what it can do:

For detailed usage, see the Installation guide and Supported Commands sections. You can use this server either through direct MCP integration or as a standalone library.

Check out the Architecture section to understand how the components work together to enable natural language control of iOS simulators.

![demo](demo/demo.gif)

### 🎮 Simulator Control
- Create and manage simulator sessions
- Boot, shutdown, and monitor simulator states
- List available and running simulators
- Focus simulator windows

### 📱 Application Management
- Install and manage iOS applications
- Launch, terminate, and uninstall apps
- Monitor app states and verify installations
- Handle app permissions and configurations

### 🖱️ UI Interaction & Testing
- Interact with the simulator UI
- Execute tap, swipe, and button press actions
- Input text and key sequences
- Access accessibility elements for UI testing
- Record videos of UI interactions

### 🛠️ Development & Debugging
- Capture screenshots and system logs
- Debug applications in real-time
- Monitor and analyze crash logs
- Install dynamic libraries and manage app data

### ⚡ Advanced Features
- Additional functionality includes:
  - Location simulation
  - Media injection
  - URL scheme handling
  - Contact database management
  - Keychain operations

For detailed usage, see the Installation guide and Supported Commands sections. You can use this server either through direct MCP integration or as a standalone library.

Check out the Architecture section to understand how the components work together to enable natural language control of iOS simulators.

## 📋 Requirements

- **macOS**: Required for iOS simulator support
- **Node.js**: v14.0.0 or higher
- **Homebrew**: Required for installing dependencies
- **XCode**: With iOS simulators installed

## 🚀 Installation

The easiest way to install this server is through Cline:

1. Simply ask Cline:
```
Add this mcp to cline https://github.com/InditexTech/mcp-server-simulator-ios-idb
```

2. Cline will handle the installation process automatically, including dependency management and configuration.

Alternatively, you can install it manually:

```bash
# 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
```

The installation process will automatically:
1. Check if you're running macOS
2. Install idb-companion via Homebrew
3. Install fb-idb via pip in the virtual environment

Note: Make sure to keep the virtual environment activated while using the server. If you close your terminal and come back later, you'll need to reactivate the virtual environment with the `source venv/bin/activate` command before running `npm start`.

## 🔌 MCP Integration

To use this server with Claude or other LLM assistants:

1. Add the server to your MCP settings in Claude Desktop:

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

2. The LLM can now use natural language commands to control iOS simulators:

```
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
```

## 📚 Usage as a Library

You can also use this package as a library in your own projects:

### 🔰 Basic Usage

```typescript
import { createMCPServer } from 'mcp-server-simulator-ios-idb';

async function main() {
  // Create an instance of the MCP server
  const { orchestrator } = createMCPServer();
  
  // 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);
```

### 🚀 Advanced Usage

You can also use the individual components directly:

```typescript
import { 
  IDBManager, 
  NLParser, 
  MCPOrchestrator,
  ParserToOrchestrator,
  OrchestratorToIDB
} from 'mcp-server-simulator-ios-idb';

// Create instances
const idbManager = new IDBManager();
const parser = new NLParser();
const orchestrator = new MCPOrchestrator(parser, idbManager);

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

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

## 🏗️ Project Structure

```
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
├── types/                   # TypeScript type definitions
├── scripts/                 # Installation scripts
├── package.json            # Project configuration
└── tsconfig.json          # TypeScript configuration
```

## 🎯 Supported Commands

The NLParser supports the following natural language commands:

### 🎮 Simulator Management
| Command | Description | Example |
|---------|-------------|---------|
| Create session | Creates a new simulator session | "create session", "create simulator iPhone 12" |
| Terminate session | Terminates the current session | "terminate session", "close simulator" |
| List simulators | Lists available simulators | "list simulators", "show simulators" |
| List booted simulators | Lists running simulators | "list booted simulators", "show running simulators" |
| Boot simulator | Boots a simulator by UDID | "boot simulator 5A321B8F-4D85-4267-9F79-2F5C91D142C2" |
| Shutdown simulator | Shuts down a simulator | "shutdown simulator 5A321B8F-4D85-4267-9F79-2F5C91D142C2" |
| Focus simulator | Brings simulator window to front | "focus simulator", "bring simulator to front" |
| List simulator sessions | Lists active simulator sessions | "list simulator sessions", "show active sessions" |

### 📱 App Management
| Command | Description | Example |
|---------|-------------|---------|
| Install app | Installs an app on the simulator | "install app /path/to/app.ipa" |
| Launch app | Launches an app on the simulator | "launch app com.example.app" |
| Terminate app | Terminates a running app | "terminate app com.example.app" |
| Uninstall app | Uninstalls an app | "uninstall app com.example.app" |
| List apps | Lists installed applications | "list apps", "show installed apps" |
| Check if app installed | Checks if an app is installed | "is app com.example.app installed" |

### 🖱️ UI Interaction
| Command | Description | Example |
|---------|-------------|---------|
| Tap | Taps at specific coordinates | "tap at 100, 200" |
| Swipe | Performs a swipe gesture | "swipe from 100, 200 to 300, 400" |
| Press button | Presses a device button | "press button HOME", "press button SIRI" |
| Input text | Types text | "input text Hello World" |
| Press key | Presses a key by code | "press key 4" |
| Press key sequence | Presses a sequence of keys | "press key sequence 4 5 6" |

### ♿ Accessibility
| Command | Description | Example |
|---------|-------------|---------|
| Describe elements | Lists all accessibility elements | "describe all elements", "show accessibility elements" |
| Describe point | Describes element at coordinates | "describe point 100, 200", "what's at 150, 300" |

### 📸 Capture and Logs
| Command | Description | Example |
|---------|-------------|---------|
| Take screenshot | Captures a screenshot | "take screenshot", "capture screen" |
| Record video | Records screen activity | "record video /path/output.mp4" |
| Stop recording | Stops video recording | "stop recording", "stop video recording" |
| Get logs | Retrieves system or app logs | "get logs", "get logs for com.example.app" |

### 🐛 Debug
| Command | Description | Example |
|---------|-------------|---------|
| Start debug | Starts a debug session | "debug app com.example.app", "start debug com.example.app" |
| Stop debug | Stops a debug session | "stop debug", "terminate debug session" |
| Debug status | Gets debug session status | "debug status", "show debug info" |

### 💥 Crash Logs
| Command | Description | Example |
|---------|-------------|---------|
| List crash logs | Lists available crash logs | "list crash logs", "show crash logs" |
| Show crash log | Shows content of a crash log | "show crash log crash_2023-01-01" |
| Delete crash logs | Deletes crash logs | "delete crash logs", "clear crash logs" |

### 🔧 Additional Commands
| Command | Description | Example |
|---------|-------------|---------|
| Install dylib | Installs a dynamic library | "install dylib /path/to/library.dylib" |
| Open URL | Opens a URL in the simulator | "open url https://example.com" |
| Clear keychain | Clears the simulator's keychain | "clear keychain" |
| Set location | Sets the simulator's location | "set location 37.7749, -122.4194" |
| Add media | Adds media to the camera roll | "add media /path/to/image.jpg" |
| Approve permissions | Approves app permissions | "approve permissions com.example.app photos camera" |
| Update contacts | Updates contacts database | "update contacts /path/to/contacts.sqlite" |

The interface supports all commands available in the idb CLI tool, providing a comprehensive set of operations for iOS simulator automation.

## 🔍 Architecture

The server consists of three main components:

1. **IDBManager**: Low-level component that interacts directly with iOS simulators through idb.
2. **NLParser**: Component that interprets natural language instructions and converts them into structured commands.
3. **MCPOrchestrator**: Central component that coordinates interactions between the parser and the IDBManager.

These components are connected through adapters:
- **ParserToOrchestrator**: Converts parser results into orchestrator commands.
- **OrchestratorToIDB**: Translates orchestrator commands into IDBManager calls.

## 🔌 MCP Integration

To use this server with the Model Context Protocol:

1. Add the server to your MCP settings:

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

2. Connect to the server in your LLM application:

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

## 🙏 Acknowledgments

This project would not be possible without [facebook/idb](https://github.com/facebook/idb), which provides the underlying iOS simulator control capabilities. We extend our sincere gratitude to the Facebook/Meta team and all contributors to the idb project for creating and maintaining such a powerful and reliable tool.

## 📄 License

This tool is available as open source under the terms of the Apache-2.0.