nzrsky/simctl-mcp-server

SimCtl MCP Server

A Model Context Protocol (MCP) server that provides structured access to iOS Simulator management via xcrun simctl commands.

Installation

Method 1: Using uvx

1. Prerequisites:

   • Python 3.13+
   • Xcode with Command Line Tools installed
   • uvx: curl -LsSf https://astral.sh/uv/install.sh | sh

2. Run directly with uvx:

   uvx simctl-mcp-server
   

Method 2: Local Development Installation

1. Prerequisites:

   • Python 3.13+
   • Xcode with Command Line Tools installed

2. Clone and install:

   git clone https://github.com/nzrsky/simctl-mcp-server
   cd simctl-mcp-server
   pip install .
   

3. Run the server:

   simctl-mcp-server
   

Method 3: Build from Source

1. Build the wheel:

   python -m build --wheel
   pip install dist/simctl_mcp_server-0.1.0-py3-none-any.whl
   

Configuration

For Claude Desktop

Add to your ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "simctl": {
      "command": "simctl-mcp-server",
      "args": [],
      "env": {}
    }
  }
}

Or if using uvx:

{
  "mcpServers": {
    "simctl": {
      "command": "uvx",
      "args": ["simctl-mcp-server"],
      "env": {}
    }
  }
}

For VS Code with MCP Extension

1. Install the MCP Extension from the VS Code marketplace
2. Add server configuration to your VS Code settings (settings.json):

{
  "mcp.servers": {
    "simctl": {
      "command": "simctl-mcp-server",
      "args": [],
      "env": {}
    }
  }
}

Or if using uvx:

{
  "mcp.servers": {
    "simctl": {
      "command": "uvx",
      "args": ["simctl-mcp-server"],
      "env": {}
    }
  }
}

3. Restart VS Code to load the MCP server
4. Use the Command Palette (Cmd+Shift+P) and search for "MCP" commands to interact with the simulator tools

For Other MCP Clients

The server runs on stdio, so you can invoke it directly:

With installed package:

simctl-mcp-server

With uvx:

uvx simctl-mcp-server

Available Tools

Device Management

• simctl_list_devices - List all simulators and their states
• simctl_boot_device - Boot a simulator
• simctl_shutdown_device - Shutdown a simulator
• simctl_create_device - Create a new simulator
• simctl_delete_device - Delete simulators

App Management

• simctl_install_app - Install an app (.app bundle or .ipa)
• simctl_launch_app - Launch an app with options
• simctl_terminate_app - Terminate a running app

Media & Screenshots

• simctl_screenshot - Take screenshots
• simctl_record_video - Record video (start recording)

Testing & Development

• simctl_push_notification - Send push notifications
• simctl_privacy_control - Manage app permissions
• simctl_set_location - Set device location/GPS
• simctl_status_bar_override - Override status bar appearance
• simctl_ui_appearance - Control light/dark mode

Usage Examples

Basic Device Operations

# List all devices
"List all available iOS simulators"

# Boot a specific device
"Boot the iPhone 15 Pro simulator"

# Create a new simulator
"Create a new iPhone 14 simulator named 'Test Device' with iOS 17.0"

App Testing

# Install and launch an app
"Install MyApp.app on the booted simulator and launch it"

# Take a screenshot
"Take a screenshot of the current simulator and save it to ~/Desktop/screenshot.png"

# Send a push notification
"Send a push notification with title 'Hello' and body 'Test message' to com.example.myapp"

UI Testing Setup

# Set up a controlled testing environment
"Set the simulator to dark mode, override the status bar to show full battery and strong WiFi, and set the time to 9:41 AM"

# Grant permissions for testing
"Grant photo library access to com.example.myapp on the booted simulator"

Location Testing

# Set specific location
"Set the simulator location to Apple Park (37.334606, -122.009102)"

# Clear location
"Clear the simulated location on the booted device"

Error Handling

The server includes comprehensive error handling:

• Command failures: Returns detailed error messages from simctl
• Missing Xcode: Detects when xcrun simctl is not available
• Invalid parameters: Validates input parameters before execution
• File operations: Handles temporary files for push notifications safely

Security Considerations

• The server only exposes read and simulator management operations
• No access to host file system beyond specified app paths
• Push notification payloads are validated for structure
• Privacy permission changes are explicit and logged

Development Notes

• Built specifically for iOS development workflows
• Optimized for common simulator management tasks
• Structured output parsing for JSON responses
• Support for both individual and batch operations
• Compatible with Xcode 15+ simulator features