iOS Simulator MCP Server

1# iOS Simulator MCP Server
2 
3[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=ios-simulator&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImlvcy1zaW11bGF0b3ItbWNwIl19) [![NPM Version](https://img.shields.io/npm/v/ios-simulator-mcp)](https://www.npmjs.com/package/ios-simulator-mcp)
4 
5A 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.
6 
7> **Security Notice**: Command injection vulnerabilities present in versions < 1.3.3 have been fixed. Please update to v1.3.3 or later. See [SECURITY.md](SECURITY.md) for details.
8 
9https://github.com/user-attachments/assets/453ebe7b-cc93-4ac2-b08d-0f8ac8339ad3
10 
11## 🌟 Featured In
12 
13This project has been featured and mentioned in various publications and resources:
14 
15- [Claude Code Best Practices article](https://www.anthropic.com/engineering/claude-code-best-practices#:~:text=Write%20code%2C%20screenshot%20result%2C%20iterate) - Anthropic's engineering blog showcasing best practices
16- [React Native Newsletter Issue 187](https://us3.campaign-archive.com/?u=78d9e37a94fa0b522939163d4&id=656ed2c2cf#:~:text=iOS%20Simulator%20MCP%20Server) - Featured in the most popular React Native community newsletter
17- [Mobile Automation Newsletter - #56](https://testableapple.com/newsletter/56/#:~:text=iOS-,iOS%20Simulator%20MCP,-%F0%9F%8E%99%EF%B8%8F%20Joshua%20Yoes) - Featured a long running newsletter about mobile testing and automation resources
18- [punkeye/awesome-mcp-server listing](https://github.com/punkpeye/awesome-mcp-servers) - Listed in one of the most popular curated awesome MCP servers collection
19 
20## Tools
21 
22### `get_booted_sim_id`
23 
24**Description:** Get the ID of the currently booted iOS simulator
25 
26**Parameters:** No Parameters
27 
28### `open_simulator`
29 
30**Description:** Opens the iOS Simulator application
31 
32**Parameters:** No Parameters
33 
34### `ui_describe_all`
35 
36**Description:** Describes accessibility information for the entire screen in the iOS Simulator
37 
38**Parameters:**
39 
40```typescript
41{
42  /**
43   * Udid of target, can also be set with the IDB_UDID env var
44   * Format: UUID (8-4-4-4-12 hexadecimal characters)
45   */
46  udid?: string;
47}
48```
49 
50### `ui_tap`
51 
52**Description:** Tap on the screen in the iOS Simulator
53 
54**Parameters:**
55 
56```typescript
57{
58  /**
59   * Press duration in seconds (decimal numbers allowed)
60   */
61  duration?: string;
62  /**
63   * Udid of target, can also be set with the IDB_UDID env var
64   * Format: UUID (8-4-4-4-12 hexadecimal characters)
65   */
66  udid?: string;
67  /** The x-coordinate */
68  x: number;
69  /** The y-coordinate */
70  y: number;
71}
72```
73 
74### `ui_type`
75 
76**Description:** Input text into the iOS Simulator
77 
78**Parameters:**
79 
80```typescript
81{
82  /**
83   * Udid of target, can also be set with the IDB_UDID env var
84   * Format: UUID (8-4-4-4-12 hexadecimal characters)
85   */
86  udid?: string;
87  /**
88   * Text to input
89   * Format: ASCII printable characters only
90   */
91  text: string;
92}
93```
94 
95### `ui_swipe`
96 
97**Description:** Swipe on the screen in the iOS Simulator
98 
99**Parameters:**
100 
101```typescript
102{
103  /**
104   * Swipe duration in seconds (decimal numbers allowed)
105   */
106  duration?: string;
107  /**
108   * Udid of target, can also be set with the IDB_UDID env var
109   * Format: UUID (8-4-4-4-12 hexadecimal characters)
110   */
111  udid?: string;
112  /** The starting x-coordinate */
113  x_start: number;
114  /** The starting y-coordinate */
115  y_start: number;
116  /** The ending x-coordinate */
117  x_end: number;
118  /** The ending y-coordinate */
119  y_end: number;
120  /** The size of each step in the swipe (default is 1) */
121  delta?: number;
122}
123```
124 
125### `ui_describe_point`
126 
127**Description:** Returns the accessibility element at given co-ordinates on the iOS Simulator's screen
128 
129**Parameters:**
130 
131```typescript
132{
133  /**
134   * Udid of target, can also be set with the IDB_UDID env var
135   * Format: UUID (8-4-4-4-12 hexadecimal characters)
136   */
137  udid?: string;
138  /** The x-coordinate */
139  x: number;
140  /** The y-coordinate */
141  y: number;
142}
143```
144 
145### `ui_view`
146 
147**Description:** Get the image content of a compressed screenshot of the current simulator view
148 
149**Parameters:**
150 
151```typescript
152{
153  /**
154   * Udid of target, can also be set with the IDB_UDID env var
155   * Format: UUID (8-4-4-4-12 hexadecimal characters)
156   */
157  udid?: string;
158}
159```
160 
161### `screenshot`
162 
163**Description:** Takes a screenshot of the iOS Simulator
164 
165**Parameters:**
166 
167```typescript
168{
169  /**
170   * Udid of target, can also be set with the IDB_UDID env var
171   * Format: UUID (8-4-4-4-12 hexadecimal characters)
172   */
173  udid?: string;
174  /** 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. */
175  output_path: string;
176  /** Image format (png, tiff, bmp, gif, or jpeg). Default is png. */
177  type?: "png" | "tiff" | "bmp" | "gif" | "jpeg";
178  /** Display to capture (internal or external). Default depends on device type. */
179  display?: "internal" | "external";
180  /** For non-rectangular displays, handle the mask by policy (ignored, alpha, or black) */
181  mask?: "ignored" | "alpha" | "black";
182}
183```
184 
185### `record_video`
186 
187**Description:** Records a video of the iOS Simulator using simctl directly
188 
189**Parameters:**
190 
191```typescript
192{
193  /** 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. */
194  output_path?: string;
195  /** Specifies the codec type: "h264" or "hevc". Default is "hevc". */
196  codec?: "h264" | "hevc";
197  /** Display to capture: "internal" or "external". Default depends on device type. */
198  display?: "internal" | "external";
199  /** For non-rectangular displays, handle the mask by policy: "ignored", "alpha", or "black". */
200  mask?: "ignored" | "alpha" | "black";
201  /** Force the output file to be written to, even if the file already exists. */
202  force?: boolean;
203}
204```
205 
206### `stop_recording`
207 
208**Description:** Stops the simulator video recording using killall
209 
210**Parameters:** No Parameters
211 
212### `install_app`
213 
214**Description:** Installs an app bundle (.app or .ipa) on the iOS Simulator
215 
216**Parameters:**
217 
218```typescript
219{
220  /**
221   * Udid of target, can also be set with the IDB_UDID env var
222   * Format: UUID (8-4-4-4-12 hexadecimal characters)
223   */
224  udid?: string;
225  /** Path to the app bundle (.app directory or .ipa file) to install */
226  app_path: string;
227}
228```
229 
230### `launch_app`
231 
232**Description:** Launches an app on the iOS Simulator by bundle identifier
233 
234**Parameters:**
235 
236```typescript
237{
238  /**
239   * Udid of target, can also be set with the IDB_UDID env var
240   * Format: UUID (8-4-4-4-12 hexadecimal characters)
241   */
242  udid?: string;
243  /** Bundle identifier of the app to launch (e.g., com.apple.mobilesafari) */
244  bundle_id: string;
245  /** Terminate the app if it is already running before launching */
246  terminate_running?: boolean;
247}
248```
249 
250## 💡 Use Case: QA Step via MCP Tool Calls
251 
252This MCP server allows AI assistants integrated with a Model Context Protocol (MCP) client to perform Quality Assurance tasks by making tool calls. This is useful immediately after implementing features to help ensure UI consistency and correct behavior.
253 
254### How to Use
255 
256After a feature implementation, instruct your AI assistant within its MCP client environment to use the available tools. For example, in Cursor's agent mode, you could use the prompts below to quickly validate and document UI interactions.
257 
258### Example Prompts
259 
260- **Verify UI Elements:**
261 
262  ```
263  Verify all accessibility elements on the current screen
264  ```
265 
266- **Confirm Text Input:**
267 
268  ```
269  Enter "QA Test" into the text input field and confirm the input is correct
270  ```
271 
272- **Check Tap Response:**
273 
274  ```
275  Tap on coordinates x=250, y=400 and verify the expected element is triggered
276  ```
277 
278- **Validate Swipe Action:**
279 
280  ```
281  Swipe from x=150, y=600 to x=150, y=100 and confirm correct behavior
282  ```
283 
284- **Detailed Element Check:**
285 
286  ```
287  Describe the UI element at position x=300, y=350 to ensure proper labeling and functionality
288  ```
289 
290- **Show Your AI Agent the Simulator Screen:**
291 
292  ```
293  View the current simulator screen
294  ```
295 
296- **Take Screenshot:**
297 
298  ```
299  Take a screenshot of the current simulator screen and save it to my_screenshot.png
300  ```
301 
302- **Record Video:**
303 
304  ```
305  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`)
306  ```
307 
308- **Stop Recording:**
309 
310  ```
311  Stop the current simulator screen recording
312  ```
313 
314- **Install App:**
315 
316  ```
317  Install the app at path/to/MyApp.app on the simulator
318  ```
319 
320- **Launch App:**
321  ```
322  Launch the Safari app (com.apple.mobilesafari) on the simulator
323  ```
324 
325## Prerequisites
326 
327- Node.js
328- macOS (as iOS simulators are only available on macOS)
329- [Xcode](https://developer.apple.com/xcode/resources/) and iOS simulators installed
330- Facebook [IDB](https://fbidb.io/) tool [(see install guide)](https://fbidb.io/docs/installation)
331 
332## Installation
333 
334This section provides instructions for integrating the iOS Simulator MCP server with different Model Context Protocol (MCP) clients.
335 
336### Installation with Cursor
337 
338Cursor manages MCP servers through its configuration file located at `~/.cursor/mcp.json`.
339 
340#### Option 1: Using NPX (Recommended)
341 
3421.  Edit your Cursor MCP configuration file. You can often open it directly from Cursor or use a command like:
343    ```bash
344    # Open with your default editor (or use 'code', 'vim', etc.)
345    open ~/.cursor/mcp.json
346    # Or use Cursor's command if available
347    # cursor ~/.cursor/mcp.json
348    ```
3492.  Add or update the `mcpServers` section with the iOS simulator server configuration:
350    ```json
351    {
352      "mcpServers": {
353        // ... other servers might be listed here ...
354        "ios-simulator": {
355          "command": "npx",
356          "args": ["-y", "ios-simulator-mcp"]
357        }
358      }
359    }
360    ```
361    Ensure the JSON structure is valid, especially if `mcpServers` already exists.
3623.  Restart Cursor for the changes to take effect.
363 
364#### Option 2: Local Development
365 
3661.  Clone this repository:
367    ```bash
368    git clone https://github.com/joshuayoes/ios-simulator-mcp
369    cd ios-simulator-mcp
370    ```
3712.  Install dependencies:
372    ```bash
373    npm install
374    ```
3753.  Build the project:
376    ```bash
377    npm run build
378    ```
3794.  Edit your Cursor MCP configuration file (as shown in Option 1).
3805.  Add or update the `mcpServers` section, pointing to your local build:
381    ```json
382    {
383      "mcpServers": {
384        // ... other servers might be listed here ...
385        "ios-simulator": {
386          "command": "node",
387          "args": ["/full/path/to/your/ios-simulator-mcp/build/index.js"]
388        }
389      }
390    }
391    ```
392    **Important:** Replace `/full/path/to/your/` with the absolute path to where you cloned the `ios-simulator-mcp` repository.
3936.  Restart Cursor for the changes to take effect.
394 
395### Installation with Claude Code
396 
397Claude Code CLI can manage MCP servers using the `claude mcp` commands or by editing its configuration files directly. For more details on Claude Code MCP configuration, refer to the [official documentation](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/tutorials#set-up-model-context-protocol-mcp).
398 
399#### Option 1: Using NPX (Recommended)
400 
4011.  Add the server using the `claude mcp add` command:
402    ```bash
403    claude mcp add ios-simulator npx ios-simulator-mcp
404    ```
4052.  Restart any running Claude Code sessions if necessary.
406 
407#### Option 2: Local Development
408 
4091.  Clone this repository, install dependencies, and build the project as described in the Cursor "Local Development" steps 1-3.
4102.  Add the server using the `claude mcp add` command, pointing to your local build:
411    ```bash
412    claude mcp add ios-simulator -- node "/full/path/to/your/ios-simulator-mcp/build/index.js"
413    ```
414    **Important:** Replace `/full/path/to/your/` with the absolute path to where you cloned the `ios-simulator-mcp` repository.
4153.  Restart any running Claude Code sessions if necessary.
416 
417## Configuration
418 
419### Environment Variables
420 
421| Variable                               | Description                                                                                                                                                                                          | Example                                  |
422| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
423| `IOS_SIMULATOR_MCP_FILTERED_TOOLS`     | A comma-separated list of tool names to filter out from being registered.                                                                                                                            | `screenshot,record_video,stop_recording` |
424| `IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR` | Specifies a default directory for output files like screenshots and video recordings. If not set, `~/Downloads` will be used. This can be handy if your agent has limited access to the file system. | `~/Code/awesome-project/tmp`             |
425| `IOS_SIMULATOR_MCP_IDB_PATH`           | Specifies a custom path to the IDB executable. If not set, `idb` will be used (assuming it's in your PATH). Useful if IDB is installed in a non-standard location.                                   | `~/bin/idb` or `/usr/local/bin/idb`      |
426 
427#### Configuration Example
428 
429```json
430{
431  "mcpServers": {
432    "ios-simulator": {
433      "command": "npx",
434      "args": ["-y", "ios-simulator-mcp"],
435      "env": {
436        "IOS_SIMULATOR_MCP_FILTERED_TOOLS": "screenshot,record_video,stop_recording",
437        "IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR": "~/Code/awesome-project/tmp",
438        "IOS_SIMULATOR_MCP_IDB_PATH": "~/bin/idb"
439      }
440    }
441  }
442}
443```
444 
445## MCP Registry Server Listings
446 
447<a href="https://glama.ai/mcp/servers/@joshuayoes/ios-simulator-mcp">
448  <img width="380" height="200" src="https://glama.ai/mcp/servers/@joshuayoes/ios-simulator-mcp/badge" alt="iOS Simulator MCP server" />
449</a>
450 
451[![MseeP.ai Security Assessment Badge](https://mseep.net/pr/joshuayoes-ios-simulator-mcp-badge.png)](https://mseep.ai/app/joshuayoes-ios-simulator-mcp)
452 
453## License
454 
455MIT
456