iOS Simulator Seamless

Control the iOS Simulator directly from Claude Code for launching apps, capturing screenshots, managing device states, and streamlining mobile development workflows through MCP.

When to Use This MCP Server

Connect this server when you need to:

• Launch, test, and debug iOS applications in the Simulator while making code changes in Claude Code without switching to Xcode
• Capture screenshots and record the Simulator state for visual testing, bug documentation, or design comparison during mobile development
• Manage Simulator device configurations including creating devices, resetting state, and switching between iOS versions programmatically

Consider alternatives when:

• You need Android device testing, where Android Emulator tools or ADB-based solutions are required instead of the iOS Simulator
• Your testing requires physical device deployment or TestFlight distribution, which involves Xcode signing and provisioning workflows

Quick Start

Configuration

Copy
name: ios-simulator-seamless
type: mcp
category: devtools

Example Connection

Copy
claude mcp:connect ios-simulator-seamless

Available Tools

boot-device:        Boot a specific iOS Simulator device by UDID or device type name
launch-app:         Install and launch an application on the currently booted Simulator
screenshot:         Capture a screenshot of the Simulator screen and save to a file path
list-devices:       List all available Simulator devices with their boot status and runtime
manage-state:       Reset content, set locale, or modify Simulator device preferences

Core Concepts

iOS Simulator MCP Overview

Aspect	Details
Transport	stdio-based process via npx running ios-simulator-mcp package
Requirement	macOS with Xcode installed; Xcode Command Line Tools must be available
Automation	Uses simctl (Simulator control CLI) under the hood for device operations
Device Support	iPhone, iPad, Apple Watch, and Apple TV Simulator runtimes
Integration	Works alongside Xcode builds or standalone with pre-built app bundles

iOS Simulator MCP Architecture

Claude Code IDE
    |
    v
[MCP Client] --stdio--> [ios-simulator-mcp]
                              |
                              v
                     [xcrun simctl CLI]
                              |
                    +---------+---------+
                    |         |         |
                    v         v         v
              [Device    [App       [Screen
              Manager]   Lifecycle]  Capture]
                    \         |         /
                     [iOS Simulator Runtime]
                       CoreSimulator.framework

Configuration

Parameter	Type	Default	Description
default_device	string	iPhone 16	Default Simulator device type to boot when not specified
default_runtime	string	latest	Default iOS runtime version; "latest" uses the newest installed
screenshot_dir	string	/tmp	Directory to save captured screenshots
boot_timeout	integer	60000	Maximum time in milliseconds to wait for Simulator boot completion
auto_boot	boolean	true	Automatically boot the default device when the MCP server starts

Best Practices

1. Use Specific Device Types for Testing - Configure default_device to match your app's target devices. Testing on iPhone SE and iPad Pro ensures your UI adapts correctly to different screen sizes and safe area insets.

2. Capture Screenshots for Visual Regression - Take screenshots at key UI states and compare them across code changes. This lightweight visual regression approach catches layout issues without requiring a full screenshot testing framework.

3. Reset Simulator State Between Test Runs - Use manage-state to reset the Simulator's content and settings between test sessions. This ensures a clean environment and prevents test pollution from leftover app data or cached state.

4. Boot Simulators Before Running Tests - Pre-boot the Simulator device before initiating test suites. Cold boot adds 15-30 seconds of startup time that can be avoided by keeping the Simulator warm during development iterations.

5. Match Runtime Versions to Deployment Target - Set default_runtime to match your app's minimum deployment target for testing backward compatibility. Testing only on the latest iOS version misses compatibility issues with older OS releases.

Common Issues

1. Xcode Command Line Tools Not Found - The MCP server requires xcrun simctl which comes with Xcode Command Line Tools. Run xcode-select --install if simctl is not available, or verify your Xcode installation path with xcode-select -p.

2. Simulator Fails to Boot - The specified device type or runtime may not be installed. Use list-devices to see available combinations, and install additional runtimes through Xcode Settings > Platforms if needed.

3. App Launch Fails with Missing Bundle - The app bundle must be built for the Simulator architecture (x86_64 or arm64 for Apple Silicon). Ensure you build with the Simulator SDK destination, not a physical device destination.