ios-simulator-mcp

MCP server that gives AI assistants (Claude, Cursor, etc.) direct control over the iOS Simulator.

Built on xcrun simctl + AppleScript. 21 tools covering device management, UI interaction, app control, sensor simulation, logs, and video recording — no Appium, no WebDriver, no extra services.

Platform: macOS only · Requires Xcode with iOS Simulator installed

Quick Install (Recommended)

Automatic installation that configures Claude Desktop, Claude Code, and Cursor:

curl -fsSL https://raw.githubusercontent.com/adborroto/ios-simulator-mcp/main/install.sh | bash

This will:

• Install the package via uv
• Auto-configure Claude Desktop
• Auto-configure Claude Code
• Auto-configure Cursor
• No manual JSON editing needed!

Uninstall

curl -fsSL https://raw.githubusercontent.com/adborroto/ios-simulator-mcp/main/uninstall.sh | bash

Manual Installation

Quick run (no install)

uv downloads and runs the package in an isolated environment:

uvx ios-simulator-mcp

Install permanently

uv tool install ios-simulator-mcp
# or
pip install ios-simulator-mcp

Configure your client

Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "ios-simulator": {
      "command": "uvx",
      "args": ["ios-simulator-mcp"]
    }
  }
}

Or run from Claude Code's terminal:

claude mcp add ios-simulator -- uvx ios-simulator-mcp

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "ios-simulator": {
      "command": "uvx",
      "args": ["ios-simulator-mcp"]
    }
  }
}

Restart Claude Desktop after saving.

Cursor

Edit .cursor/mcp.json in your project root (or ~/.cursor/mcp.json globally):

{
  "mcpServers": {
    "ios-simulator": {
      "command": "uvx",
      "args": ["ios-simulator-mcp"]
    }
  }
}

VS Code (with Copilot / MCP extension)

Edit .vscode/mcp.json:

{
  "servers": {
    "ios-simulator": {
      "type": "stdio",
      "command": "uvx",
      "args": ["ios-simulator-mcp"]
    }
  }
}

Pin a specific simulator (optional)

If you have multiple simulators and want to target a specific one without passing udid to every tool:

{
  "mcpServers": {
    "ios-simulator": {
      "command": "uvx",
      "args": ["ios-simulator-mcp"],
      "env": {
        "IOS_SIM_DEFAULT_UDID": "A1B2C3D4-E5F6-7890-ABCD-EF1234567890"
      }
    }
  }
}

Get your UDID with xcrun simctl list devices or by asking the AI to call list_simulators.

Accessibility permission (required for tap & swipe)

tap and swipe use AppleScript to send clicks to the Simulator window. macOS requires Accessibility access for the process running the MCP server — typically your terminal app or the MCP client itself.

Go to System Settings → Privacy & Security → Accessibility and add:

• Your terminal app (Terminal, iTerm2, Warp, etc.) if running Claude Code from the terminal
• Claude Desktop or Cursor if using those clients

Without this, tap and swipe will return an error. take_screenshot, input_text, and all other tools work without this permission.

Tools reference

All tools accept an optional udid parameter. When omitted, the server auto-detects the booted simulator or falls back to IOS_SIM_DEFAULT_UDID.

Device management

#### list_simulators

List all simulators known to Xcode, with their name, UDID, state, and runtime.

# Example prompt
"List all booted iOS 18 simulators"
→ calls list_simulators(runtime_filter="iOS 18", state_filter="Booted")

Returns: devices[], total, booted_count, booted[]

#### get_booted_simulator

Returns the currently booted simulator(s). No parameters.

Useful at the start of a session to confirm which device is active before running other tools.

Returns: booted[], primary (first booted device), count

#### boot_simulator

Boot a simulator by UDID. The UDID must come from list_simulators.

# Example prompt
"Boot the iPhone 16 Pro simulator"
→ calls list_simulators() first to find the UDID, then boot_simulator(udid="...")

The Simulator app opens automatically. Allow a few seconds before interacting.

#### shutdown_simulator

Shutdown a booted simulator.

Screenshots & UI interaction

#### take_screenshot

Capture the current simulator screen and return it as an inline image.

The image is returned directly to the AI so it can analyze the UI, read text, locate elements, and decide where to tap — no file path needed.

# Example workflow
1. take_screenshot()          → AI sees the current screen
2. tap(x=196, y=430)          → AI taps a button it located
3. take_screenshot()          → AI verifies the result

#### tap

Tap at a point on the simulator screen.

Coordinates use the same space as screenshots. (0, 0) is the top-left corner of the device screen (not the window chrome).

Requires Accessibility permission — see above.

# Example prompt
"Tap the Login button"
→ AI calls take_screenshot() to see where Login is, then tap(x=196, y=512)

#### swipe

Perform a swipe gesture between two points.

# Scroll down a list
swipe(x1=196, y1=600, x2=196, y2=200, duration=0.4)

# Swipe left (e.g. next page in onboarding)
swipe(x1=350, y1=400, x2=40, y2=400, duration=0.3)

Requires Accessibility permission — see above.

#### input_text

Type text into the currently focused text field on the simulator.

Tap the target field first to focus it, then call input_text.

# Tap the email field, then type
tap(x=196, y=280)
input_text(text="[email protected]")

App control

#### launch_app

Launch an app on the simulator.

launch_app(bundle_id="com.example.MyApp")

#### terminate_app

Force-terminate a running app.

#### open_url

Open a URL or deep link in the simulator. Useful for testing deep link routing without tapping through the UI.

open_url(url="myapp://home/settings")
open_url(url="https://example.com")

#### uninstall_app

Remove an app and all its data from the simulator. Equivalent to long-pressing → Remove App on device.

Permissions

#### grant_permission / revoke_permission

Grant or revoke a privacy permission for an app without going through the system dialog.

Available permissions: all, calendar, camera, contacts, faceid, homekit, location, medialibrary, microphone, motion, photos, reminders, siri

grant_permission(bundle_id="com.example.MyApp", permission="camera")
revoke_permission(bundle_id="com.example.MyApp", permission="photos")

Sensor simulation

#### set_location

Override the GPS coordinates reported to all apps on the simulator.

set_location(latitude=48.8566, longitude=2.3522)  # Paris

#### set_appearance

Switch between light and dark mode.

#### set_battery

Override the battery indicator in the status bar.

set_battery(level=15, state="discharging")  # test low-battery UI

Logs

#### get_logs

Stream simulator system logs for a short period and return the captured lines. Useful for debugging crashes, reading print statements, and checking network errors.

# Get the last 50 log lines from your app
get_logs(process="MyApp", lines=50)

# Find crash-related lines
get_logs(keyword="crash", timeout_seconds=5)

# Flutter / React Native: filter by your process
get_logs(process="Runner", keyword="ERROR")

Returns: lines[], count, stderr

Media & recording

#### add_media

Inject a photo or video file into the simulator's Photos library. Useful for testing image picker flows.

add_media(file_path="/Users/you/Desktop/test-photo.jpg")

#### start_video_recording

Start recording the simulator screen to an .mp4 file.

Returns the output path and PID. Call stop_video_recording() to finalize the file.

#### stop_video_recording

Stop an active screen recording and save the file.

Returns: output_path, size_bytes

Example workflows

Test a login flow end-to-end

1. boot_simulator(udid="...")          boot iPhone 16 Pro
2. launch_app(bundle_id="com.myapp")  open the app
3. take_screenshot()                   confirm login screen is shown
4. tap(x=196, y=320)                  tap email field
5. input_text(text="[email protected]")
6. tap(x=196, y=390)                  tap password field
7. input_text(text="secret123")
8. tap(x=196, y=490)                  tap Login button
9. take_screenshot()                   verify logged-in state

Test location-based features

1. grant_permission(bundle_id="com.myapp", permission="location")
2. set_location(latitude=40.7128, longitude=-74.0060)  New York
3. launch_app(bundle_id="com.myapp")
4. take_screenshot()                                   verify location shown

Debug a crash

1. launch_app(bundle_id="com.myapp")
2. get_logs(process="MyApp", keyword="error", timeout_seconds=10)
   → returns relevant error lines
3. open_url(url="myapp://the-crashing-screen")
4. get_logs(process="MyApp", lines=200)

Record a demo video

1. start_video_recording(output_path="/tmp/demo.mp4")
2. ... perform actions ...
3. stop_video_recording()   → returns /tmp/demo.mp4

Environment variables

Limitations

• macOS only. Requires Xcode 14+ with iOS Simulator.
• tap and swipe require Accessibility permission for the process running the server (terminal or MCP client). See Accessibility permission.
• tap / swipe bring the Simulator window to the foreground.
• Device width auto-detection covers iPhone 12 and later. For older or iPad device types, set IOS_SIM_DEVICE_WIDTH manually.
• One video recording active per simulator at a time.

License

MIT