xcsimctl

by nzrsky

442 downloads

Not rated

GitHub

About

An MCP server that wraps xcrun simctl to provide structured, programmatic control of iOS Simulators. It is designed for iOS developers and QA engineers who need to automate simulator workflows from AI assistants or development tools.

Details

Author: nzrsky
Downloads: 442
Categories: Developer Tools, Community, Other

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name xcsimctl

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

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

JSON

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

JSON

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

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

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

JSON

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

JSON

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

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

From the repository

Install with uvx simctl-mcp-server or by cloning the repo and running pip install .. Configure by adding the server to your MCP client (e.g., Claude Desktop or VS Code MCP extension) with command simctl-mcp-server or uvx simctl-mcp-server. The server communicates over stdio and exposes tools that can be called directly from your AI assistant.

`simctl_list_devices`

List available iOS simulators and their states. Args: format: Output format (json or text). Defaults to json. filter: Optional filter term (e.g., 'available', 'iPhone', 'iOS 17') Returns: List of available simulators

`simctl_boot_device`

Boot a simulator device. Args: device: Device UDID, name, or 'booted' for current device arch: Architecture to use when booting (arm64 or x86_64) Returns: Success message

`simctl_shutdown_device`

Shutdown a simulator device. Args: device: Device UDID, name, or 'booted' for current device Returns: Success message

`simctl_create_device`

Create a new simulator device. Args: name: Name for the new device device_type: Device type identifier (e.g., 'iPhone 15 Pro') runtime: Runtime identifier (e.g., 'iOS 17.0') Returns: Created device information

`simctl_delete_device`

Delete simulator devices. Args: devices: List of device UDIDs, names, or 'unavailable' to delete all unavailable devices Returns: Success message

`simctl_install_app`

Install an app on a simulator device. Args: device: Device UDID, name, or 'booted' for current device app_path: Path to .app bundle or .ipa file Returns: Success message

`simctl_launch_app`

Launch an app on a simulator device. Args: device: Device UDID, name, or 'booted' for current device bundle_id: App bundle identifier wait_for_debugger: Wait for debugger to attach before launching console_mode: Console output mode (none, console, console-pty) args: Additional launch arguments Returns: Launch result

`simctl_terminate_app`

Terminate an app on a simulator device. Args: device: Device UDID, name, or 'booted' for current device bundle_id: App bundle identifier Returns: Success message

`simctl_screenshot`

Take a screenshot of a simulator device. Args: device: Device UDID, name, or 'booted' for current device output_path: Path where to save the screenshot format: Image format (png, jpeg) display: Display to capture (internal, external) Returns: Success message

`simctl_record_video`

Start recording video of a simulator device. Args: device: Device UDID, name, or 'booted' for current device output_path: Path where to save the video codec: Video codec (hevc, h264) display: Display to record (internal, external) Returns: Recording start message

`simctl_push_notification`

Send a push notification to a simulator device. Args: device: Device UDID, name, or 'booted' for current device payload: Push notification payload as JSON object bundle_id: Target app bundle identifier (optional if specified in payload) Returns: Success message

`simctl_privacy_control`

Control app privacy permissions on a simulator device. Args: device: Device UDID, name, or 'booted' for current device action: Privacy action (grant, revoke, reset) service: Privacy service (photos, camera, microphone, location, etc.) bundle_id: App bundle identifier (optional) Returns: Success message

`simctl_set_location`

Set or clear device location on a simulator. Args: device: Device UDID, name, or 'booted' for current device action: Location action (set, clear, run) latitude: Latitude coordinate (required for 'set' action) longitude: Longitude coordinate (required for 'set' action) scenario: Location scenario (required for 'run' action) Returns: Success message

`simctl_status_bar_override`

Override status bar appearance on a simulator device. Args: device: Device UDID, name, or 'booted' for current device action: Status bar action (override, clear) time: Time to display (e.g., "9:41") data_network: Data network type (wifi, 3g, 4g, lte, lte-a, lte+, 5g, 5g+, 5g-uw) wifi_bars: WiFi signal strength (0-3) cellular_bars: Cellular signal strength (0-4) battery_level: Battery level percentage (0-100) battery_state: Battery state (charging, charged, discharging) Returns: Success message

`simctl_ui_appearance`

Get or set UI appearance (light/dark mode) on a simulator device. Args: device: Device UDID, name, or 'booted' for current device appearance: UI appearance (light, dark). If not provided, returns current appearance. Returns: Current or updated appearance

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

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

McpServers

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

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

```

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

simctl_list_devices

simctl_boot_device

simctl_shutdown_device

simctl_create_device

simctl_delete_device

simctl_install_app

simctl_launch_app

simctl_terminate_app

simctl_screenshot

simctl_record_video

simctl_push_notification

simctl_privacy_control

simctl_set_location

simctl_status_bar_override

simctl_ui_appearance

Claude Desktop / Cursor

McpServers

SimCtl MCP Server

Installation

Method 1: Using uvx

Method 2: Local Development Installation

Method 3: Build from Source

Configuration

For Claude Desktop

For VS Code with MCP Extension

For Other MCP Clients

Available Tools

Device Management

App Management

Media & Screenshots

Testing & Development

Usage Examples

Basic Device Operations

Install

More like this

Sequential Thinking

Sentry

Github

Filesystem

EverArt

Google Drive

`simctl_list_devices`

`simctl_boot_device`

`simctl_shutdown_device`

`simctl_create_device`

`simctl_delete_device`

`simctl_install_app`

`simctl_launch_app`

`simctl_terminate_app`

`simctl_screenshot`

`simctl_record_video`

`simctl_push_notification`

`simctl_privacy_control`

`simctl_set_location`

`simctl_status_bar_override`

`simctl_ui_appearance`