iOS Simulator MCP Server

Project

Author: joshuayoes
Repository: github.com/joshuayoes/ios-simulator-mcp
License: MIT
Category: Mobile & Desktop Automation

Tech

Runtime / language: nodeTypeScript
Transports: stdio
Remote available: No
Authentication: Not specified

Activity

GitHub stars: 2,194
Last commit: Aug 13, 2026
Data as of: Oct 16, 2026

Overview

iOS Simulator MCP Server connects assistant workflows to Apple's simulator environment on macOS. It combines device discovery, accessibility inspection, touch gestures, and app management so an assistant can inspect an interface and then act on it. Developers can use it after implementing a feature to check labels, enter sample text, verify tap responses, or examine a screen. The README includes client configurations for Cursor and Claude Code.

Accessibility tools describe either the full screen or a particular coordinate, while element search can match labels or identifiers with optional type and case filters. The server also exposes screenshots and a compressed image view, giving the assistant both structured information and visual evidence. Video recording supports documenting an interaction sequence. App tools cover installation, launch, termination, installed-app discovery, and URL opening, including link-testing scenarios. Simulator targets can be supplied explicitly or selected through an environment variable.

The documented prerequisites are Node.js, macOS, Xcode with simulators, and Facebook IDB. A package launch through npx avoids the local build steps, although a source-build option is also shown. Environment settings can filter tools and choose where captures are saved. Text input is restricted to printable ASCII. The security notice recommends version 1.3.3 or newer because earlier releases contained command injection vulnerabilities, making version choice an important setup consideration.

Install & configure

Requirements

Node.js
macOS
Xcode and installed iOS simulators
Facebook IDB

Documented launch / install command

npx -y ios-simulator-mcp

Use release 1.3.3 or later according to the README security notice. The default capture directory is ~/Downloads when no output directory is configured.

Claude Desktop

Cursor

VS Code

Windsurf

Claude Code

Config file · macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Use Settings → Developer → Edit Config when available. Do not assume a Linux configuration path; check the client documentation for your platform. Remote servers use the app’s connector flow when supported, not the local stdio file shown here. Merge this example with existing settings; do not overwrite unrelated servers.

Claude Desktop configuration

{
  "mcpServers": {
    "ios-simulator-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "ios-simulator-mcp"
      ],
      "env": {
        "IDB_UDID": "<optional target simulator UUID>",
        "IOS_SIMULATOR_MCP_FILTERED_TOOLS": "<optional comma-separated tool names to exclude>",
        "IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR": "<optional directory for screenshots and recordings>"
      }
    }
  }
}

Read the Claude Desktop setup guide

Config file · Project: .cursor/mcp.json

User: ~/.cursor/mcp.json

The project path is relative to the workspace root. The tilde denotes your user home directory. Use Cursor’s MCP settings to confirm which configuration and scope your installed version is reading. Merge this example with existing settings; do not overwrite unrelated servers.

Cursor configuration

{
  "mcpServers": {
    "ios-simulator-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "ios-simulator-mcp"
      ],
      "env": {
        "IDB_UDID": "<optional target simulator UUID>",
        "IOS_SIMULATOR_MCP_FILTERED_TOOLS": "<optional comma-separated tool names to exclude>",
        "IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR": "<optional directory for screenshots and recordings>"
      }
    }
  }
}

Read the Cursor setup guide

Config file · Workspace: .vscode/mcp.json

For user scope, use the “MCP: Open User Configuration” command if available. Do not guess a user configuration path across operating systems, profiles, containers, or remote workspaces; check the client documentation. Merge this example with existing settings; do not overwrite unrelated servers.

VS Code configuration

{
  "servers": {
    "ios-simulator-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "ios-simulator-mcp"
      ],
      "env": {
        "IDB_UDID": "<optional target simulator UUID>",
        "IOS_SIMULATOR_MCP_FILTERED_TOOLS": "<optional comma-separated tool names to exclude>",
        "IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR": "<optional directory for screenshots and recordings>"
      }
    }
  }
}

Read the VS Code setup guide

Config file · macOS/Linux: ~/.codeium/windsurf/mcp_config.json

Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json

Open the MCP configuration through Windsurf’s settings when possible to confirm the active file. Paths can differ in managed or future releases; check the client documentation if this location is not present. Merge this example with existing settings; do not overwrite unrelated servers.

Windsurf configuration

{
  "mcpServers": {
    "ios-simulator-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "ios-simulator-mcp"
      ],
      "env": {
        "IDB_UDID": "<optional target simulator UUID>",
        "IOS_SIMULATOR_MCP_FILTERED_TOOLS": "<optional comma-separated tool names to exclude>",
        "IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR": "<optional directory for screenshots and recordings>"
      }
    }
  }
}

Read the Windsurf setup guide

Config file · Project scope: .mcp.json at the repository root

The project file uses mcpServers. For user scope, use claude mcp add --scope user rather than assuming .mcp.json in your home directory is the user configuration. Check the client documentation for managed settings and storage details. Merge this example with existing settings; do not overwrite unrelated servers.

Claude Code configuration

{
  "mcpServers": {
    "ios-simulator-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "ios-simulator-mcp"
      ],
      "env": {
        "IDB_UDID": "<optional target simulator UUID>",
        "IOS_SIMULATOR_MCP_FILTERED_TOOLS": "<optional comma-separated tool names to exclude>",
        "IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR": "<optional directory for screenshots and recordings>"
      }
    }
  }
}

Read the Claude Code setup guide

Examples are translated from the published configuration. Supply your own credentials and verify requirements in the upstream README. Remote connectors are shown only where a supported configuration format is known.

Tools

Source: repository tool metadata. Tool descriptions are a documented snapshot, not a live capability check.

Tool	What it does
get_booted_sim_id	Identify the simulator that is currently running.
open_simulator	Start the Simulator application.
ui_describe_all	Read accessibility details for the visible simulator screen.
ui_tap	Send a touch at specified screen coordinates.
ui_type	Enter printable ASCII text into the simulator.
ui_swipe	Perform a swipe between two screen positions.
ui_describe_point	Inspect the accessibility element at a screen position.
ui_find_element	Find accessibility elements matching labels, identifiers, or type filters.
ui_view	Return a compressed image of the current simulator display.
screenshot	Save a simulator screen capture to a file.
record_video	Begin a simulator screen recording through simctl.
stop_recording	End the active simulator video capture.
install_app	Load a local .app bundle or .ipa package into the simulator.
launch_app	Start an installed app using its bundle identifier.
terminate_app	Stop a running app identified by its bundle ID.
open_url	Open a URL in the simulator for navigation or link testing.
list_apps	Enumerate installed apps with their names and bundle IDs.

Names, permissions, and defaults can change. Check the current upstream documentation before granting access.

Use cases

Check accessibility labels after an interface change.
Exercise tap, typing, and swipe flows in an app.
Capture screenshots or videos for QA evidence.
Install and launch a simulator build and test deep links.

Strengths

Provides both accessibility-tree data and screen images.
Covers UI interaction and app lifecycle tasks.
Allows tool filtering and configurable capture directories.

Limitations

Requires macOS, Xcode simulators, and IDB.
The typing tool accepts printable ASCII only.
Versions before 1.3.3 have a documented command injection issue.

Frequently asked questions

The documented setup requires macOS because it operates Apple's iOS simulators.

Yes. ui_find_element searches accessibility labels or unique identifiers and supports additional matching filters.

The README uses ~/Downloads unless IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR is configured.

The security notice says the issue is fixed in version 1.3.3 and recommends that version or newer.

Independent listing, not an affiliation or security review. Grant the least access needed and verify the upstream instructions before running code.

Server facts

Project

Tech

Activity

Tags

Overview

Install & configure

Requirements

Tools

Use cases

Strengths

Limitations

Frequently asked questions

Related MCP servers

Desktop Commander MCP

Mobile Next Mobile MCP

Windows-MCP

iMCP

Home Assistant MCP Server

Android MCP Server

Server facts

Project

Tech

Activity

Tags

Overview

Install & configure

Requirements

Tools

Use cases

Strengths

Limitations

Frequently asked questions

Can this run on Windows or Linux?

Can the assistant find controls by label?

Where are recordings saved by default?

Which release addresses the documented injection issue?

Related MCP servers

Desktop Commander MCP

Mobile Next Mobile MCP

Windows-MCP

iMCP

Home Assistant MCP Server

Android MCP Server