ios-sim-mcp

A Model Context Protocol (MCP) server for iOS Simulator automation. Enables AI assistants to visually interact with iOS apps running in the simulator.

How It Works

This MCP server wraps Facebook's idb (iOS Development Bridge) to provide isolated, headless control of iOS simulators. Unlike approaches that control your mouse/keyboard, idb injects touch events directly into the simulator:

• Runs in the background - doesn't take over your screen
• Isolated - you can use your computer while it runs
• Reliable - uses the same infrastructure Facebook uses for testing

Requirements

• macOS (iOS Simulator only runs on Mac)
• Xcode with iOS Simulator installed
• Node.js 18+
• idb (install via steps below)

Installing idb

# Install idb-companion (the daemon)
brew tap facebook/fb
brew install idb-companion

# Install idb (the Python CLI client)
pip3 install fb-idb

Installation

Option 1: Install from npm (recommended)

npm install -g ios-sim-mcp

Option 2: Clone and build

git clone https://github.com/artmamedov/ios-sim-mcp.git
cd ios-sim-mcp
npm install
npm run build

Usage with Claude Code

claude mcp add ios-sim -s user -- npx ios-sim-mcp

Or if installed from source:

claude mcp add ios-sim -s user -- node /path/to/ios-sim-mcp/dist/index.js

Coordinate System

All coordinates are in POINTS, not pixels.

• Points are device-independent units used by iOS
• Use get_screen_size to get both pixel and point dimensions
• Use describe_screen to get element coordinates in points
• Common sizes: iPhone 17 Pro is 393x852 points

Common Workflows

1. Getting Started

list_simulators              → Find available simulators and their UDIDs
boot_simulator(udid)         → Boot the simulator you want
screenshot                   → Verify it's running, see the screen

2. Finding and Tapping UI Elements

# Option A: Search by label (recommended)
find_elements(label: "Sign In")  → Returns elements with matching labels
tap_element(label: "Sign In")    → Find and tap in one step

# Option B: Use coordinates from accessibility tree
describe_screen              → Get all elements with their frame coordinates
tap(x: 196, y: 425)          → Tap at the element's center

3. Filling Out Forms

tap_element(label: "Email")      → Focus the email field
type_text(text: "user@test.com") → Type the email
press_key(key: "tab")            → Move to next field
type_text(text: "password123")   → Type the password
tap_element(label: "Submit")     → Submit the form

4. Scrolling and Navigation

# Scroll down (swipe up)
swipe(startX: 200, startY: 600, endX: 200, endY: 200)

# Scroll up (swipe down)
swipe(startX: 200, startY: 200, endX: 200, endY: 600)

# Go back to home screen
press_button(button: "home")

5. Testing Deep Links

open_url(url: "myapp://profile/settings")  → Open custom URL scheme
screenshot                                  → Verify the right screen loaded

Available Tools

Simulator Management

Tool	Description	Returns
list_simulators	List all iOS simulators with state	Array: [{name, udid, state, type, os_version}]
boot_simulator	Boot simulator by UDID	Confirmation string
shutdown_simulator	Shutdown simulator	Confirmation string

Visual Feedback

Tool	Description	Returns
screenshot	Capture simulator screen	Base64 PNG image
get_screen_size	Get dimensions	{pixels: {w,h}, points: {w,h}, scale}

UI Discovery

Tool	Description	Returns
describe_screen	Get all UI elements	Array: [{type, label, value, frame, enabled}]
describe_point	Get element at coordinates	Element info string
find_elements	Search elements by label	Array of matching elements

Interactions

Tool	Description	Returns
tap	Tap at x,y coordinates (points)	Confirmation string
tap_element	Find element by label and tap it	Confirmation with coordinates
swipe	Swipe between two points	Confirmation string
type_text	Type into focused field	Confirmation string
press_key	Press keyboard key (enter, delete, tab, escape)	Confirmation string
press_button	Press device button (home, lock, siri, apple_pay)	Confirmation string

App Management

Tool	Description	Returns
list_apps	List installed apps	App list with bundle IDs
launch_app	Launch app by bundle ID	Confirmation string
terminate_app	Terminate running app	Confirmation string
open_url	Open URL (http or custom scheme)	Confirmation string

Element Discovery

The describe_screen tool returns UI elements in this format:

[
  {
    "type": "Button",
    "label": "Sign In",
    "value": null,
    "frame": {"x": 147, "y": 400, "width": 100, "height": 50},
    "enabled": true
  },
  {
    "type": "TextField",
    "label": "Email",
    "value": "",
    "frame": {"x": 20, "y": 200, "width": 353, "height": 44},
    "enabled": true
  }
]

To tap an element, calculate its center:

• centerX = frame.x + frame.width / 2
• centerY = frame.y + frame.height / 2

Or use tap_element which does this automatically.

Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Claude/LLM    │────▶│  ios-sim-mcp    │────▶│  idb companion  │
│                 │ MCP │  (this server)  │ CLI │  (Facebook's)   │
└─────────────────┘     └─────────────────┘     └────────┬────────┘
                                                         │
                                                         ▼
                                                ┌─────────────────┐
                                                │  iOS Simulator  │
                                                │  (Xcode)        │
                                                └─────────────────┘

Configuration

The server looks for idb in these locations:

1. IDB_PATH environment variable (if set)
2. ~/Library/Python/3.9/bin/idb
3. /opt/homebrew/bin/idb
4. /usr/local/bin/idb
5. System PATH

Troubleshooting

"No booted simulator found"

Use list_simulators to find available simulators, then boot_simulator with the UDID.

"idb not found"

Install idb: pip3 install fb-idb

"No Companion Connected"

The idb companion usually starts automatically. If issues persist:

idb_companion --udid <simulator-udid>

Tap not hitting the right element

1. Coordinates must be in points, not pixels
2. Use describe_screen to get exact element frames
3. Use tap_element with the element's label for more reliable tapping

Element not found by label

1. Use describe_screen to see all available labels
2. Labels are case-insensitive partial matches
3. Some elements may not have accessibility labels set

License

MIT

Credits

• Facebook idb - The underlying automation framework
• Model Context Protocol - The protocol specification