iOS Simulator

You can control and inspect iOS simulators via a Model Context Protocol (MCP) server. This server lets you query booted simulators, interact with the UI, take screenshots or videos, install and launch apps, and describe UI elements to support automated QA and AI-assisted testing on macOS.

How to use

Use this MCP server with an MCP client to perform QA and UI automation tasks on iOS simulators. You can start from a simple workflow: boot a simulator, describe the screen and elements, tap or type into the UI, take a screenshot or record a video, install or launch apps, and verify results. Tools are exposed as callable commands, and environment variables tailor behavior like default output locations and available features.

How to install

Prerequisites: install Node.js and ensure macOS with Xcode and iOS simulators are available. You also need the IDB tool if you plan to interoperate with iOS devices in testing.

# Install prerequisites (if needed, use your package manager)
# Ensure Node.js is installed
node -v
npm -v

# Option 1: Use the MCP server via NPX (recommended integration path)
npx ios-simulator-mcp

# Option 2: Run the MCP server from a local build after cloning the project
# 1) Clone the repository
# git clone https://github.com/joshuayoes/ios-simulator-mcp
# 2) Install dependencies
# npm install
# 3) Build the project
# npm run build
# 4) Run the server from your local build
# node /full/path/to/your/ios-simulator-mcp/build/index.js

Configuration and usage notes

Environment variables customize server behavior and tool visibility. The following variables appear in runtime configurations and should be mirrored in your MCP client setups if you want consistent behavior across environments.

{
  "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"
      }
    }
  },
  "envVars": [
    {"name": "IOS_SIMULATOR_MCP_FILTERED_TOOLS", "description": "A comma-separated list of tools to filter out from registration", "required": true, "example": "screenshot,record_video,stop_recording"},
    {"name": "IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR", "description": "Default directory for output files like screenshots and videos", "required": true, "example": "~/Code/awesome-project/tmp"},
    {"name": "IOS_SIMULATOR_MCP_IDB_PATH", "description": "Custom path to the IDB executable", "required": true, "example": "~/bin/idb"}
  ]
}

Tools and actions you can call

This server exposes a variety of commands to interact with iOS simulators. You can describe the entire screen, tap or type input, swipe, query UI elements, take screenshots, record video, install and launch apps, and describe specific UI elements by coordinates.

get_booted_sim_id
open_simulator
ui_describe_all
ui_tap
ui_type
ui_swipe
ui_describe_point
ui_view
screenshot
record_video
stop_recording
install_app
launch_app

Security and best practices

Keep your tools up to date to avoid command injection vulnerabilities and follow the security recommendations for your automation environment. Use environment-scoped credentials and restrict access to the MCP client and its runtime configuration where possible.

Troubleshooting

If you encounter issues starting the MCP server or connecting to simulators, verify your environment variables are set correctly and that the path to IDB and the build artifacts exist. Check that the iOS Simulator is installed and booted, and ensure the correct UDID is addressed if you specify one in tool calls.

Available tools

get_booted_sim_id

Returns the ID of the currently booted iOS simulator.

open_simulator

Launches the iOS Simulator application.

ui_describe_all

Describes accessibility information for the entire screen.

ui_tap

Simulates a tap on the screen at given coordinates with optional duration.

ui_type

Inputs text into the iOS Simulator.

ui_swipe

Performs a swipe gesture from start to end coordinates with optional duration and delta.

ui_describe_point

Returns accessibility element information at given coordinates.

ui_view

Retrieves a compressed screenshot image of the current simulator view.

screenshot

Saves a screenshot to a specified output path with selectable image format.

record_video

Records a video of the simulator using the system's recording tool.

stop_recording

Stops the ongoing video recording.

install_app

Installs an app bundle (.app or .ipa) on the simulator.

launch_app

Launches an app by bundle identifier, with an option to terminate if already running.