iOS Simulator MCP Setup for Claude Code and Cursor
Treat the booted iOS Simulator as the source of truth: install Node.js, Xcode with an iOS simulator, and Facebook IDB on macOS, then connect one MCP client with npx -y ios-simulator-mcp. Verify that the client can inspect the accessibility tree before you tap, type, swipe, install, or launch anything.
Treat the booted iOS Simulator as the source of truth: install Node.js, Xcode with an iOS simulator, and Facebook IDB on macOS, then connect one MCP client with npx -y ios-simulator-mcp. Verify that the client can inspect the accessibility tree before you tap, type, swipe, install, or launch anything.
Table of contents
- What the iOS Simulator MCP server exposes
- Install the macOS, Xcode, and IDB prerequisites
- Add the server to Claude Code or Cursor
- Verify the booted simulator and accessibility tree
- Test taps, typing, screenshots, and launches safely
- Diagnose no-device and IDB errors
- FAQ
What the iOS Simulator MCP server exposes
The iOS Simulator MCP server lets an MCP-compatible assistant inspect and control the currently booted iOS Simulator. Treat that simulator state as the source of truth, then validate accessibility before sending interaction commands.
The server can:
- Read the currently booted simulator.
- Open the Simulator app.
- Describe accessibility information for the whole screen or a single point.
- Search the accessibility tree for elements.
- Tap, type, and swipe.
- Capture compressed screen views and full screenshots.
- Record and stop video.
- Install and launch apps by bundle identifier.
This makes the server suitable for QA workflows in which an assistant checks and documents UI behavior after a feature is implemented. It is built on Facebook’s IDB tool and Apple’s simctl, and runs locally over stdio. The iOS Simulator MCP repository provides the project’s installation and connection context.
The practical order matters. First establish that the assistant can see the booted simulator. Next inspect the accessibility tree. Only then perform gestures, enter text, capture evidence, or install and launch an app.
For a directory-level reference, see MCPtrove’s iOS Simulator MCP Server entry.
Install the macOS, Xcode, and IDB prerequisites
Install the required tools on macOS: Node.js, Xcode with iOS simulators, and Facebook IDB. iOS simulators are available only on macOS, so a Windows or Linux setup cannot provide the required simulator environment.
Use these prerequisites:
- Install Node.js.
- Install Xcode.
- Install at least one iOS Simulator through Xcode.
- Install Facebook IDB by following the official IDB installation documentation.
- Open and boot the simulator you intend to inspect.
The server depends on Apple’s simulator tooling and IDB. Apple’s Simulator and device documentation explains the surrounding Xcode workflow, while the IDB documentation covers the separate Facebook tooling requirement.
Before connecting an MCP client, confirm that the intended simulator is booted and visible in the Simulator app. A client connected to the server without a booted simulator cannot inspect the screen or accessibility tree that your workflow depends on.
Keep the first setup small: one Mac, one booted simulator, one MCP client, and one target app. This makes it easier to identify whether a problem comes from the client connection, simulator state, or IDB installation.
Add the server to Claude Code or Cursor
Add one MCP server entry to Claude Code or Cursor that launches the exact command npx -y ios-simulator-mcp. Configure the entry to use stdio transport; no authentication is required.
The command is:
npx -y ios-simulator-mcp
In the client’s MCP configuration, represent that command using the client’s normal server-entry fields. The executable is npx, and the command arguments are -y and ios-simulator-mcp. Do not add unverified flags, credentials, or alternate transports.
MCP uses client-server connections in which the client starts or connects to a server and then invokes its available tools. The MCP architecture documentation explains this general relationship. For client configuration checks, MCPtrove’s configuration validator can be a practical next step.
After saving the entry, connect only one client first. A successful connection should give the assistant access to the server’s simulator-control capabilities, but the meaningful verification is whether it can identify and inspect the booted simulator.
If Claude Code and Cursor use different configuration screens, follow each client’s MCP settings format while preserving the same launch command and stdio transport.
Verify the booted simulator and accessibility tree
Boot one simulator, connect one client, and ask the assistant to identify the current simulator before requesting any interaction. Then inspect the accessibility tree for the whole screen and search for a known element.
A useful verification sequence is:
- Confirm that a simulator is currently booted.
- Open the Simulator app if it is not already visible.
- Request a description of the whole screen’s accessibility information.
- Search the accessibility tree for a visible control.
- Describe accessibility information at a specific point if the target is unclear.
- Compare the reported element with what is visible in the simulator.
The accessibility tree should be your first validation surface because it gives the assistant structured information about visible UI elements. Search by a stable visible label or role before tapping. If the result does not match the intended control, stop and inspect the screen again.
This sequence also separates simulator discovery from interaction. If the assistant cannot describe the screen, gestures are premature. The MCP debugging guide provides broader guidance for diagnosing MCP communication and tool-call problems.
Once accessibility inspection works, record the simulator state you are using in your QA notes. That keeps later screenshots, videos, and launch results tied to a known booted environment.
Test taps, typing, screenshots, and launches safely
Use the accessibility tree to select a target, perform one action at a time, and inspect the resulting screen after each action. For app operations, verify the bundle identifier before installing or launching.
A controlled interaction sequence looks like this:
- Search the accessibility tree for the intended control.
- Confirm its label, position, or role.
- Tap the target.
- Inspect the updated accessibility tree.
- Type only after confirming that the intended field is focused.
- Use a swipe only after checking the current screen and expected direction.
- Capture a compressed screen view for quick inspection or a full screenshot for evidence.
- Record video when a sequence of UI behavior needs to be documented, then stop recording when the sequence ends.
The server also supports installing and launching apps by bundle identifier. Treat the identifier as an explicit input to verify, especially when more than one app or build is available in the simulator.
This workflow keeps each action observable. If a tap changes the screen unexpectedly, the next accessibility inspection can show whether the target moved, disappeared, or produced a new state. Apple’s simulator documentation is the relevant reference for the underlying Apple simulator environment.
For MCP-specific safety, preserve user control over actions that change simulator state and validate tool inputs before execution. The MCP security best practices describe these general principles.
For a broader test workflow, MCPtrove’s MCP server testing guide can help organize setup, execution, and evidence collection.
Diagnose no-device and IDB errors
For a no-device error, first confirm that an iOS Simulator is booted and that the client is connected to the intended server entry. For an IDB error, verify the Facebook IDB installation and then reconnect the client.
Use this decision table:
| Symptom | Likely check | Next action |
|---|---|---|
| No booted device | The Simulator app has no active booted device | Boot one simulator, then retry simulator inspection |
| The client cannot connect | The MCP entry does not launch the expected command | Confirm it launches npx -y ios-simulator-mcp over stdio |
| IDB-related error | Facebook IDB is missing or unavailable | Recheck the IDB installation guide |
| Screen inspection fails | The simulator is booted but the accessibility request does not return useful data | Reopen the Simulator app and retry the accessibility inspection |
| Tool calls behave unexpectedly | Client-server communication needs diagnosis | Consult the MCP debugging guide |
Do not add authentication settings to this server connection: the verified setup uses no authentication. Do not add alternate command flags while troubleshooting, because that changes the connection you are trying to validate.
If you need an IDB-focused directory reference, review MCPtrove’s iOS Simulator MCP Server with IDB entry. Once the server can inspect the booted simulator and return accessibility information, repeat the tap, typing, screenshot, and launch checks in order.