iOS Simulator

A Model Context Protocol (MCP) server for interacting with iOS simulators. This server allows you to interact with iOS simulators by getting information about them, controlling UI interactions, and inspecting UI elements.

Security Notice: Command injection vulnerabilities present in versions < 1.3.3 have been fixed. Please update to v1.3.3 or later. SeeSECURITY.mdfor details.

https://github.com/user-attachments/assets/a88e449c-8f1d-46a5-9816-0f97e071c460

- Claude Code Best Practices article- Anthropic's engineering blog showcasing best practices
- React Native Newsletter Issue 187- Featured in the most popular React Native community newsletter
- Mobile Automation Newsletter - #56- Featured a long running newsletter about mobile testing and automation resources
- punkeye/awesome-mcp-server listing- Listed in one of the most popular curated awesome MCP servers collection

{ /  Udid of target, can also be set with the IDB_UDID env var  Format: UUID (8-4-4-4-12 hexadecimal characters) / udid?: string; }

{ /  Press duration in seconds (decimal numbers allowed) / duration?: string; /  Udid of target, can also be set with the IDB_UDID env var  Format: UUID (8-4-4-4-12 hexadecimal characters) / udid?: string; / The x-coordinate / x: number; / The y-coordinate / y: number; }

{ /  Udid of target, can also be set with the IDB_UDID env var  Format: UUID (8-4-4-4-12 hexadecimal characters) / udid?: string; /  Text to input  Format: ASCII printable characters only / text: string; }

{ /  Swipe duration in seconds (decimal numbers allowed) / duration?: string; /  Udid of target, can also be set with the IDB_UDID env var  Format: UUID (8-4-4-4-12 hexadecimal characters) / udid?: string; / The starting x-coordinate / x_start: number; / The starting y-coordinate / y_start: number; / The ending x-coordinate / x_end: number; / The ending y-coordinate / y_end: number; / The size of each step in the swipe (default is 1) / delta?: number; }

{ /  Udid of target, can also be set with the IDB_UDID env var  Format: UUID (8-4-4-4-12 hexadecimal characters) / udid?: string; / The x-coordinate / x: number; / The y-coordinate / y: number; }

{ / Array of search strings. An element matches if ANY string matches against its AXLabel or AXUniqueId / search: string[]; / Filter by element type (e.g. 'Button', 'StaticText', 'Group'). Case-insensitive exact match / type?: string; / Match mode: 'substring' (default) or 'exact' / matchMode?: "substring" | "exact"; / Whether search matching is case-sensitive (default: false) / caseSensitive?: boolean; /  Udid of target, can also be set with the IDB_UDID env var  Format: UUID (8-4-4-4-12 hexadecimal characters) / udid?: string; }

Description:Get the image content of a compressed screenshot of the current simulator view

{ /  Udid of target, can also be set with the IDB_UDID env var  Format: UUID (8-4-4-4-12 hexadecimal characters) / udid?: string; }

{ /  Udid of target, can also be set with the IDB_UDID env var  Format: UUID (8-4-4-4-12 hexadecimal characters) / udid?: string; / File path where the screenshot will be saved. If relative, it uses the directory specified by the IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR env var, or ~/Downloads if not set. / output_path: string; / Image format (png, tiff, bmp, gif, or jpeg). Default is png. / type?: "png" | "tiff" | "bmp" | "gif" | "jpeg"; / Display to capture (internal or external). Default depends on device type. / display?: "internal" | "external"; / For non-rectangular displays, handle the mask by policy (ignored, alpha, or black) / mask?: "ignored" | "alpha" | "black"; }

Description:Records a video of the iOS Simulator using simctl directly

{ /  Udid of target, can also be set with the IDB_UDID env var  Format: UUID (8-4-4-4-12 hexadecimal characters) / udid?: string; / Optional output path. If not provided, a default name will be used. The file will be saved in the directory specified by IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR or in ~/Downloads if the environment variable is not set. / output_path?: string; / Specifies the codec type: "h264" or "hevc". Default is "hevc". / codec?: "h264" | "hevc"; / Display to capture: "internal" or "external". Default depends on device type. / display?: "internal" | "external"; / For non-rectangular displays, handle the mask by policy: "ignored", "alpha", or "black". / mask?: "ignored" | "alpha" | "black"; / Force the output file to be written to, even if the file already exists. / force?: boolean; }

Description:Stops the simulator video recording using killall

Description:Installs an app bundle (.app or .ipa) on the iOS Simulator

{ /  Udid of target, can also be set with the IDB_UDID env var  Format: UUID (8-4-4-4-12 hexadecimal characters) / udid?: string; / Path to the app bundle (.app directory or .ipa file) to install / app_path: string; }

Description:Launches an app on the iOS Simulator by bundle identifier

{ /  Udid of target, can also be set with the IDB_UDID env var  Format: UUID (8-4-4-4-12 hexadecimal characters) / udid?: string; / Bundle identifier of the app to launch (e.g., com.apple.mobilesafari) / bundle_id: string; / Terminate the app if it is already running before launching / terminate_running?: boolean; / Optional environment variables passed via SIMCTL_CHILD_ to simctl launch / env?: Record<string, string>; }

Notes:Environment variables are passed usingSIMCTL_CHILD_becausesimctl launchdoes not support--env/--envson all Xcode versions.

{ "bundle_id": "com.example.app", "terminate_running": true, "env": { "FOO": "bar", "BAZ": "qux" } }

Description:Terminates a running app on the iOS Simulator by bundle identifier. Useful for testing cold-start flows and verifying crash recovery without reinstalling the app.

{ /  Udid of target, can also be set with the IDB_UDID env var  Format: UUID (8-4-4-4-12 hexadecimal characters) / udid?: string; / Bundle identifier of the app to terminate (e.g., com.apple.mobilesafari) / bundle_id: string; }

Description:Opens a URL or deep link in the iOS Simulator. Handleshttps://URLs (via Safari), custom URL schemes, and universal links — essential for testing deep-link routing and OAuth redirect flows.

{ /  Udid of target, can also be set with the IDB_UDID env var  Format: UUID (8-4-4-4-12 hexadecimal characters) / udid?: string; / The URL or deep link to open (e.g., https://example.com or myapp://screen/detail) / url: string; }

Description:Lists all installed apps on the iOS Simulator with their bundle identifiers and display names, sorted alphabetically. Removes the need to look up bundle IDs manually before callinglaunch_apporterminate_app.

{ /  Udid of target, can also be set with the IDB_UDID env var  Format: UUID (8-4-4-4-12 hexadecimal characters) / udid?: string; }

Verify all accessibility elements on the current screen

Enter "QA Test" into the text input field and confirm the input is correct

Tap on coordinates x=250, y=400 and verify the expected element is triggered

Swipe from x=150, y=600 to x=150, y=100 and confirm correct behavior

Describe the UI element at position x=300, y=350 to ensure proper labeling and functionality

Show Your AI Agent the Simulator Screen:*

Take a screenshot of the current simulator screen and save it to my_screenshot.png

Start recording a video of the simulator screen (saves to the default output directory, which is ~/Downloads unless overridden by IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR)

Stop the current simulator screen recording

Install the app at path/to/MyApp.app on the simulator

Launch the Safari app (com.apple.mobilesafari) on the simulator

Agents can waste a lot of iterations tapping and swiping their way to a deeply nested route. When your app registers a URL scheme (or Universal Link), it's usually faster to jump directly to the target screen instead of navigating there step by step.

You can open a deep link withuri-scheme:

npx uri-scheme open "myapp://products/42" --ios

xcrun simctl openurl booted "myapp://products/42"

Open the deep link myapp://products/42 in the simulator, then verify the product details screen is shown

- Node.js 20 or later
- macOS (as iOS simulators are only available on macOS)
- Xcodeand iOS simulators installed
- FacebookIDBtool(see install guide)

# Open with your default editor (or use 'code', 'vim', etc.) open ~/.cursor/mcp.json # Or use Cursor's command if available # cursor ~/.cursor/mcp.json

{ "mcpServers": { // ... other servers might be listed here ... "ios-simulator": { "command": "npx", "args": ["-y", "ios-simulator-mcp"] } } }

Ensure the JSON structure is valid, especially ifmcpServersalready exists.

If you prefer pnpm, use itsdlxrunner instead:

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

Restart Cursor for the changes to take effect.
- Clone this repository:

git clone https://github.com/joshuayoes/ios-simulator-mcp cd ios-simulator-mcp

npm install # or, using pnpm (installs from the committed pnpm-lock.yaml): pnpm install

{ "mcpServers": { // ... other servers might be listed here ... "ios-simulator": { "command": "node", "args": ["/full/path/to/your/ios-simulator-mcp/build/index.js"] } } }

Claude Code CLI can manage MCP servers using theclaude mcpcommands or by editing its configuration files directly. For more details on Claude Code MCP configuration, refer to theofficial documentation.
- Add the server using theclaude mcp addcommand:

claude mcp add ios-simulator npx ios-simulator-mcp # or, with pnpm: claude mcp add ios-simulator -- pnpm dlx ios-simulator-mcp

claude mcp add ios-simulator -- node "/full/path/to/your/ios-simulator-mcp/build/index.js"

{ "mcpServers": { "ios-simulator": { "command": "npx", "args": ["-y", "ios-simulator-mcp"], "env": { "IOS_SIMULATOR_MCP_FILTERED_TOOLS": "screenshot,record_video,stop_recording", "IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR": "~/Code/awesome-project/tmp", "IOS_SIMULATOR_MCP_IDB_PATH": "~/bin/idb" } } } }

This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases.

Extentos is a multi-vendor development platform for adding smart-glasses capabilities to existing iOS and Android apps. The simplest analogy is Stripe for smart glasses