iOS Simulator Control via MCP Server

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

ℹ️ Overview

This MCP server bridges the gap between LLMs and iOS simulators, allowing comprehensive control through natural language commands. It supports a wide range of operations, from simulator management to application testing and debugging.

🎮 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

• Location simulation
• Media injection
• URL scheme handling
• Contact database management
• Keychain operations

📋 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

Via Cline

1. Ask Cline:
   Add this mcp to cline https://github.com/InditexTech/mcp-server-simulator-ios-idb
2. Cline handles the installation process automatically.

Manual Installation

# 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

🔌 MCP Integration

To use this server with Claude or other LLM assistants:

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

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

1. Use natural language commands:

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

🔰 Basic Usage

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

async function main() {
  const { orchestrator } = createMCPServer();

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

  await orchestrator.processInstruction('tap at 100, 200');

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

main().catch(console.error);

🚀 Advanced Usage

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

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

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

🎮 Simulator Management

📱 App Management

🖱️ UI Interaction

♿ Accessibility

📸 Capture and Logs

🐛 Debug

💥 Crash Logs

🔧 Additional Commands

🔍 Architecture

The server consists of three main components:
1. IDBManager: Low-level component that interacts directly with iOS simulators through idb.
2. NLParser: Interprets natural language instructions and converts them into structured commands.
3. MCPOrchestrator: 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.

🙏 Acknowledgments

This project relies on facebook/idb for iOS simulator control capabilities. Special thanks to the Facebook/Meta team and all contributors to the idb project.

📄 License

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