Overview
What is Xcode Simctl?
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.
How to use Xcode Simctl?
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.
Key features of Xcode Simctl
- List, boot, shutdown, create, and delete simulators
- Install, launch, and terminate apps on simulators
- Take screenshots and record video
- Send push notifications to a running app
- Manage privacy permissions and location simulation
- Override status bar and UI appearance (light/dark mode)
Use cases of Xcode Simctl
- Automating iOS app installation, launch, and screenshot capture in CI
- Setting up a known simulator state (dark mode, status bar tweaks) for UI testing
- Testing push notification delivery end-to-end without a real device
- Simulating location for GPS-dependent app features
- Granting or revoking privacy permissions during test runs
FAQ from Xcode Simctl
What prerequisites are required?
Python 3.13+, Xcode with Command Line Tools, and optionally uvx for running the server directly.
How do I configure Xcode Simctl for Claude Desktop?
Add a simctl entry to ~/Library/Application Support/Claude/claude_desktop_config.json with command: "simctl-mcp-server" or "uvx" with args ["simctl-mcp-server"].
What simulator management operations are supported?
All standard xcrun simctl operations: device lifecycle (list, boot, shutdown, create, delete), app management (install, launch, terminate), media capture, push notifications, privacy permissions, location, status bar, and appearance.
Does Xcode Simctl have access to my host file system?
Access is limited to specified app paths and temporary files for push notifications. No broad file system access is exposed.
How are errors handled?
Command failures return detailed error messages from simctl. Missing Xcode, invalid parameters, and unsafe file operations are detected and reported.
