📌Overview

Purpose: To provide a standardized communication layer between iOS simulators and the Model Context Protocol (MCP), enabling programmatic control of simulators.

Overview: This framework is designed to bridge the gap between iOS simulators and the MCP, utilizing the appium-ios-simulator and MCP TypeScript SDK. By leveraging stdio for communication, it allows seamless integration with MCP-compatible clients, such as Claude Desktop.

Key Features:

Simulator Management: Start, stop, and manage multiple iOS simulator instances easily.
Application Control: Install, launch, and terminate applications on simulators, with capabilities to take screenshots and perform user interactions.

📱 MCP Server for iOS Simulator

A server that implements the Model Context Protocol (MCP) for iOS simulators, built on top of appium-ios-simulator and utilizing the MCP TypeScript SDK.

📋 Overview

This project provides a bridge between iOS simulators and the Model Context Protocol, enabling standardized communication and programmatic control of iOS simulators. It uses stdio as its transport mechanism, making it ideal for integration with Claude Desktop and other MCP-compatible clients.

🏗️ Architecture

The server consists of three main components:

Simulator Management Layer - Handles iOS simulator lifecycle and interactions
MCP Protocol Implementation - Implements the Model Context Protocol using the TypeScript SDK with stdio transport
Logger Component - Provides file-based logging without interfering with the stdio transport

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  MCP Protocol   │     │     Stdio       │     │    Simulator    │
│  Implementation │◄────┤    Transport    │◄────┤   Management    │
│                 │     │                 │     │      Layer      │
└─────────────────┘     └─────────────────┘     └─────────────────┘
        ▲                                                ▲
        │                                                │
        ▼                                                ▼
┌─────────────────┐                             ┌─────────────────┐
│   MCP Client    │                             │  iOS Simulator  │
│  (e.g. Claude)  │                             │                 │
└─────────────────┘                             └─────────────────┘

✨ Features

Start, stop, and manage iOS simulator instances
Boot and shutdown simulators
Install and launch applications on simulators
Take screenshots of simulator screens
Perform taps on coordinates
Support for multiple concurrent simulator sessions
Comprehensive file-based logging without console output
Error-resilient operation

📋 Prerequisites

Node.js (v16 or later)
macOS (required for iOS simulators)
Xcode with iOS simulators installed
TypeScript 4.5+

🔧 Installation

# Clone the repository
git clone https://github.com/atom2ueki/mcp-server-ios-simulator.git
cd mcp-server-ios-simulator

# Install dependencies
npm install

⚙️ Configuration

Configure via the src/config.ts file:

const config = {
  simulator: {
    defaultDevice: process.env.SIMULATOR_DEFAULT_DEVICE || 'iPhone 16',
    defaultOS: process.env.SIMULATOR_DEFAULT_OS || '18.2',
    timeout: parseInt(process.env.SIMULATOR_TIMEOUT || '30000', 10),
  }
};

Set environment variables to customize:

SIMULATOR_DEFAULT_DEVICE=iPhone 16
SIMULATOR_DEFAULT_OS=18.2
SIMULATOR_TIMEOUT=30000

🚀 Usage

Building and Starting the Server

# Build the project
npm run build

# Start the server
npm start

MCP Tools

The server offers two approaches for controlling iOS simulators:

Direct Simulator Management (Recommended)

Works directly with simulator UDIDs, no sessions needed:

list-available-simulators — List all available simulators with UDIDs
boot-simulator-by-udid — Boot a simulator using its UDID
shutdown-simulator-by-udid — Shutdown a simulator using its UDID
list-booted-simulators — List all currently booted simulators

Use this to boot, use, and shut down simulators directly.

Session-Based Management (Advanced)

Uses a session layer with custom session IDs:

list-simulator-sessions — List all active sessions
create-simulator-session — Create a new session
terminate-simulator-session — Terminate a session (shuts down and cleans up)
create-and-boot-simulator — Create session and boot it
boot-simulator — Boot simulator for a session
shutdown-simulator — Shutdown simulator for a session

Use this when tracking metadata or managing simulators by custom IDs.

Application Management

install-app — Install an app on a simulator
launch-app — Launch an app on a simulator
terminate-app — Terminate a running app on a simulator

Interaction Tools

take-screenshot — Take a screenshot of the simulator screen
tap-coordinate — Perform a tap at specified coordinates

Example Usage with Claude Desktop

Configure Claude Desktop with this server as an MCP tool, specifying the command and path to dist/index.js.
Control iOS simulators directly from Claude Desktop via:

Direct UDID Approach (Recommended):

"Show me all available iOS simulators"
"Boot the iOS simulator with UDID "
"Shut down the simulator with UDID "

Session-Based Approach (Advanced):

"Create a new simulator session for iPhone 16 Pro with iOS 18.2"
"Boot the simulator for session "
"Take a screenshot of the simulator for session "
"Terminate the simulator session "

👨‍💻 Development

Project Structure

src/
├── simulator/       # Simulator management layer
├── mcp/             # MCP protocol implementation
├── bridge/          # Bridge component
├── utils/           # Utility functions including logger
├── config.ts        # Configuration handling
└── index.ts         # Entry point

Building the Project

# Install dependencies
npm install

# Build
npm run build

📜 License

This project is licensed under the MIT License.

🙏 Acknowledgments

appium-ios-simulator for iOS simulator interaction
Model Context Protocol for protocol and SDK