mcp-server-simulator-ios-idb
by: InditexTech
A Model Context Protocol (MCP) server that enables LLMs to interact with iOS simulators through natural language commands.
📌Overview
Purpose: To provide a seamless connection between Large Language Models (LLMs) and iOS simulators, allowing for control through natural language commands.
Overview: The MCP server for iOS Simulator acts as a bridge facilitating interaction between LLMs and iOS simulators, enabling users to perform operations such as managing application states and simulating user interactions through intuitive commands.
Key Features:
-
Simulator Control: Create and manage simulator sessions, boot or shut down simulators, and monitor their states.
-
Application Management: Install, launch, terminate, and uninstall iOS applications while verifying installations and handling app permissions.
-
UI Interaction & Testing: Execute various UI actions like tapping and swiping, input text, and access accessibility elements for comprehensive UI testing.
-
Development & Debugging: Capture screenshots and logs, perform real-time debugging, and manage app data with advanced operation capabilities.
-
Advanced Features: Includes options for location simulation, media injection, URL handling, contact management, and keychain operations.
📱 MCP Server for iOS Simulator
A Model Context Protocol (MCP) server that enables LLMs to interact with iOS simulators through natural language commands.
ℹ️ Overview
This MCP server bridges Large Language Models (LLMs) and iOS simulators, offering comprehensive control through natural language commands.
🎮 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
Using Cline
Simply ask Cline:
Add this mcp to cline https://github.com/InditexTech/mcp-server-simulator-ios-idb
Cline will handle installation, dependencies, and configuration 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
The installation will:
- Check macOS environment
- Install idb-companion via Homebrew
- Install fb-idb via pip in the virtual environment
Note: Keep the virtual environment activated while using the server. Reactivate it with source venv/bin/activate if your terminal session closes.
🔌 MCP Integration
To use this server with Claude or other LLM assistants:
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": {}
}
}
}
Example commands the LLM can use:
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
| 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 for comprehensive iOS simulator automation.
🔍 Architecture
The server consists of three main components:
- IDBManager: Low-level component interacting with iOS simulators via idb.
- NLParser: Interprets natural language instructions to structured commands.
- MCPOrchestrator: Coordinates the parser and IDBManager interactions.
These components connect 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:
- Add the server to your MCP settings:
{
"mcpServers": {
"ios-simulator": {
"command": "node",
"args": ["/path/to/mcp-server-simulator-ios-idb/dist/index.js"],
"env": {}
}
}
}
- Connect to the server in your LLM application:
const result = await useMcpTool({
serverName: "ios-simulator",
toolName: "process-instruction",
arguments: {
instruction: "create simulator session"
}
});
🙏 Acknowledgments
This project is based on facebook/idb, providing iOS simulator control capabilities. Thanks to the Facebook/Meta team and all contributors for their work on this powerful tool.
📄 License
This tool is open source under the Apache-2.0 license.