https://github.com/inditextech/mcp-server-simulator-ios-idb

A Model Context Protocol (MCP) server that enables LLMs to interact with iOS simulators through natural language commands.
https://github.com/inditextech/mcp-server-simulator-ios-idb
claude cline mcp typescript
Last synced: 2 months ago
JSON representation
A Model Context Protocol (MCP) server that enables LLMs to interact with iOS simulators through natural language commands.
Host: GitHub
URL: https://github.com/inditextech/mcp-server-simulator-ios-idb
Owner: InditexTech
License: apache-2.0
Created: 2025-03-18T11:11:28.000Z (7 months ago)
Default Branch: main
Last Pushed: 2025-04-25T08:31:47.000Z (5 months ago)
Last Synced: 2025-04-25T09:41:08.605Z (5 months ago)
Topics: claude, cline, mcp, typescript
Language: TypeScript
Homepage:
Size: 18.1 MB
Stars: 67
Watchers: 2
Forks: 3
Open Issues: 3
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project

README

          # 📱 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.
ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/inditextech/mcp-server-simulator-ios-idb

Awesome Lists containing this project

README
