MCP Server Simulator IOS IDB

How to use

You connect your MCP-enabled client to the server and issue natural language instructions. The server interprets your request, translates it into simulator commands, and returns structured results you can act on in your application. Typical workflows include creating a simulator session, installing or launching apps, interacting with the UI via taps or text input, and capturing visuals or logs for debugging.

How to install

Prerequisites you need before installation are macOS for iOS simulator support, Node.js version 14.0.0 or higher, Homebrew for dependencies, and XCode with iOS simulators installed.

Install via the package manager helper tool for a streamlined setup:

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

Or install manually by cloning the project, setting up a Python virtual environment, installing dependencies, and starting the server:

# 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

During installation the process will perform checks for macOS, install idb-companion via Homebrew, and install fb-idb via pip in the virtual environment. Keep the virtual environment active while using the server; reactivate it with source venv/bin/activate if you close and reopen the terminal.

MCP integration

To use this server with an MCP client, add the server configuration to your MCP settings. The following example shows how to register the local stdio server using Node to run the built distribution.

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

Once connected, you can issue natural language commands such as creating a simulator session, installing or launching apps, tapping at coordinates, or taking screenshots.

Example client usage (TypeScript) shows how to process an instruction and handle results via the MCP tool integration.

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

Usage as a library

You can incorporate this MCP server directly in your project. The basic usage creates the server and processes instructions through the orchestrator.

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
  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 lets you access individual components directly, such as the IDB manager, parser, and orchestrator, for more granular control.

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 and commands

The server is organized into adapters, an IDB manager, an MCP implementation, an orchestrator, and a natural language parser. Core interactions flow from the NLParser to the MCPOrchestrator and then to the IDBManager.

Supported commands and capabilities

This server exposes a comprehensive set of simulator controls, including creating and terminating sessions, installing and launching apps, UI interactions like taps and swipes, accessibility queries, screenshots, logs, and debugging aids. It also supports advanced features such as location simulation, media injection, URL handling, and keychain operations.

Notes and best practices

Keep the virtual environment activated while running the server. If you close your terminal, remember to re-activate the environment before starting again. When registering MCP configurations, provide the exact command and path to the runtime index to ensure seamless startup.

processInstruction

Processes natural language instructions and returns structured results from the MCP server.