iOS Simulator MCP: Setup Guide (2026)

TL;DR + what you actually need

Everything you need to get the iOS Simulator MCP server running, in four lines:

• npm package: ios-simulator-mcp — stdio only, run via npx -y ios-simulator-mcp. No remote endpoint; it must run locally on macOS.
• Claude Code install: claude mcp add ios-simulator npx ios-simulator-mcp
• Prerequisites: Node.js, macOS, Xcode with an iOS Simulator, and Facebook’s IDB tool on your PATH.
• Security: pin >=1.3.3. Anything older carries a command-injection CVE (more below). This is non-negotiable.

The server is open-source (MIT) and maintained by Joshua Yoes. It was name-checked in Anthropic’s Claude Code best practices as part of the “write code, screenshot result, iterate” loop. The rest of this guide explains the pieces, the tools, and the gotchas.

What it is, in one line

iOS Simulator MCP is a Model Context Protocol server that exposes the iOS Simulator’s controls — tap, type, swipe, screenshot, record, and accessibility inspection — as tools an AI agent can call. MCP is the JSON-RPC wire format that lets any LLM client talk to any tool server; if that’s new, start with our What is MCP guide.

Concretely: you tell Claude “tap the login button and check the error state,” and the agent calls ui_tap and ui_describe_all against the running simulator, then reports what it saw. No hand on the trackpad.

Why it exists

The agentic dev loop has a blind spot on mobile. An agent can write a SwiftUI view or a React Native screen, but it cannot see whether the button it just wired up actually renders, fires, or lands in the right place. Before this server, the loop broke at the worst moment: the agent finished the code and then waited for a human to build, launch the simulator, click around, and paste back what happened.

iOS Simulator MCP closes that loop. The agent drives the simulator itself — it taps, reads the accessibility tree to confirm the right element appeared, screenshots the result, and iterates. One Reddit developer building Expo React Native apps described exactly this gap: they wanted the agent “controlling iOS simulator… clicking through my app, testing features.” That is the problem this server solves.

Apple ships the primitives — simctl for device control, the Accessibility API for the element tree — but they are CLI verbs and private frameworks, not agent tools. This project wraps them (plus Facebook’s IDB) behind clean MCP tool definitions so the agent doesn’t have to know any of that.

The named pieces

Four moving parts. Understanding them makes every install error and tool failure obvious instead of mysterious.

The takeaway: the server is thin glue. The real work is done by IDB and simctl, which is why most failures trace back to one of those two not being installed or not on the PATH.

Install (Claude Code & every client)

Prerequisites first, because the server is useless without them. On a Mac: install Xcode and at least one iOS Simulator, then install Facebook’s IDB. Confirm IDB is reachable:

# verify the bridge is installed and on PATH
idb --version

# boot a simulator if you don't have one open
open -a Simulator

The fastest path for the most-searched client, Claude Code, is one command:

claude mcp add ios-simulator npx ios-simulator-mcp

Restart any running Claude Code session so it picks up the new tool catalogue. The install panel below has the exact config for every other client — Cursor, VS Code, Windsurf, Claude Desktop, and the manual JSON fallback. Tap your client’s row, copy the snippet, restart, done. The panel pulls its config straight from our catalog, so it stays in sync with the published package.

One-line install · iOS Simulator

Open server page

Install

Cursor

One-click install

1-Click

VS Code

One-click install

1-Click

Claude Desktop

Copy configuration

Claude Code

Copy CLI command

CLI

Gemini

Copy CLI command

CLI

Codex

Copy CLI command

CLI

Windsurf

Copy configuration

ChatGPT

Add via Settings → Connectors

M

Manual

Copy configuration

The raw JSON, if you prefer editing config by hand (this is what the Cursor / Claude Desktop entry looks like):

{
  "mcpServers": {
    "ios-simulator": {
      "command": "npx",
      "args": ["-y", "ios-simulator-mcp"]
    }
  }
}

Three environment variables are worth knowing. They’re optional but each solves a real problem:

• IOS_SIMULATOR_MCP_FILTERED_TOOLS — a comma-separated list of tools to not register (e.g. screenshot,record_video,stop_recording). Trim the tool surface the agent sees.
• IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR — where screenshots and recordings land. Defaults to ~/Downloads; point it inside your repo if your agent has restricted filesystem access.
• IOS_SIMULATOR_MCP_IDB_PATH — a custom path to the idb binary, for when IDB lives somewhere non-standard and isn’t on PATH.

Running Claude Code specifically? Our Claude Code client page covers scopes and config file locations. Browse every client and its config path at mcp.directory/clients.

Smallest end-to-end loop

Here’s the whole value in one exchange. Your app is running in the simulator. You type into Claude Code:

You: The login screen is open in the simulator. Tap the
"Sign In" button without filling anything, then tell me what
validation error shows up.

Claude:
  → get_booted_sim_id        (finds the running simulator)
  → ui_describe_all          (reads the accessibility tree)
  → ui_find_element          (locates "Sign In" by AXLabel)
  → ui_tap  x=196 y=612      (taps it)
  → ui_describe_all          (re-reads the screen)

Claude: I tapped "Sign In" with empty fields. A red
"Email is required" label appeared below the email field,
and the button stayed disabled until I cleared it. The
password field showed no error — you may want to validate
both on submit, not just email.

That last sentence is the point. The agent didn’t just click — it read the result back from the accessibility tree and gave you a finding. No screenshot to eyeball, no manual repro. That is the loop iOS Simulator MCP unlocks.

The tools, grouped

The server exposes a focused set of tools. Grouping them by job makes the surface easy to hold in your head.

Device & app lifecycle

• get_booted_sim_id — returns the UDID of the currently booted simulator. Most other tools accept an optional udid; this is how the agent finds the default.
• open_simulator — launches the Simulator app.
• install_app — installs an .app or .ipa bundle onto the simulator.
• launch_app — launches an installed app by bundle identifier, with optional terminate_running and child environment variables.

UI interaction

• ui_tap — tap at x, y with an optional press duration.
• ui_type — input text (ASCII printable characters).
• ui_swipe — swipe from a start point to an end point, with a step size and duration.

Inspection (how the agent “sees”)

• ui_describe_all — dumps accessibility info for the entire screen. The agent’s primary way to understand state.
• ui_describe_point — returns the element at a specific coordinate.
• ui_find_element — searches the accessibility tree for elements matching label or ID strings, with substring/exact match and type filters. Added in a later release; it’s the cleanest way to target a control by name instead of guessing pixels.
• ui_view — returns a compressed screenshot as image content the agent can look at directly, useful for vision-capable models.

Capture

• screenshot — saves a full-resolution screenshot (png, jpeg, and other formats) to a path.
• record_video / stop_recording — record the simulator screen to a file, then stop. Handy for capturing a repro of a flaky interaction.

Opinionated takeaway: lean on ui_find_element and ui_describe_all over raw coordinate taps. Coordinates drift across device sizes and layout changes; matching by accessibility label survives a redesign. If a control has no label, that’s a real accessibility bug the agent just surfaced for free.

What we got wrong

Three things bit us when we first wired this into a React Native QA loop. They’re all avoidable once you know.

1. We ran whatever version npx grabbed — that was the dangerous default. Early on we pinned nothing and let npx resolve the package. That’s fine now, but if you’d done it during the window when a vulnerable release was current, you’d have shipped a command-injection hole into your dev machine (see the next section). The lesson: for any MCP server that shells out to a binary, pin a known-good version and read its security history before you trust it with your shell.

2. We blamed the server when the real problem was IDB. The first “tap” call failed with an opaque error and we spent twenty minutes re-reading the server config. The actual cause: idb wasn’t on the PATH. The interaction and inspection tools are thin wrappers over IDB; if IDB isn’t reachable, they all die. Check idb --version first, every time.

3. We let the agent tap by coordinates and it broke on the next screen size. Hardcoded x/y taps worked on the device we tested and silently missed on a different simulator. Switching the prompt to “find the element labeled X and tap it” — which routes through ui_find_element — made the flow stable across devices.

The CVE you must pin past

This is the most important section in the guide, so here’s the full story. Versions of ios-simulator-mcp below 1.3.3 were vulnerable to OS command injection (GHSA-6f6r-m9pv-67jw, CWE-78). The ui_tap tool built its IDB command by string-concatenating tool arguments — duration, udid, x, y — straight into a shell exec call. An argument containing shell metacharacters like ; or && would break out of the intended idb command and run arbitrary commands on the host.

Why this matters more than a normal library CVE: the arguments come from the LLM. A prompt-injection attack — a malicious string in a webpage, a file, or a test fixture the agent reads — could steer the model into calling ui_tap with a payload, and the injection would execute on your machine. The reporter, Liran Tal of Snyk, demonstrated exactly this class of attack against MCP servers that build shell commands from untrusted input. Severity was rated medium (CVSS 6.0), but the blast radius is your local shell.

The maintainer patched it in v1.3.3 (“Cmd Injection Security Hardening”) by moving off unsafe shell concatenation, and the README now carries a security notice up top. The fix is real and the current releases are clean. The action for you is simply: pin >=1.3.3, and treat this as a reminder that any MCP server which shells out deserves a look at its security history before you grant it your shell.

Real workflows

Four loops where this server earns its place in the toolchain. Each assumes the server is installed and a simulator is booted.

Recipe 1 — QA a feature right after building it

The canonical use, and the one Anthropic highlighted. After the agent implements a screen, prompt: “Open the new settings screen, toggle dark mode, and confirm every label is still readable.” The agent launches the app, navigates, taps the toggle, and reads back the accessibility tree to verify the controls. Build, exercise, report — without you leaving the chat.

Recipe 2 — Reproduce and record a bug

A user reports a crash on a specific tap sequence. Tell the agent the steps and ask it to record_video while it reproduces them. You get a screen recording of the exact repro saved to your output directory, with the agent’s description of where it diverged from expected behaviour.

Recipe 3 — Accessibility audit

Ask: “Walk the main flow and list every interactive element that has no accessibility label.” Because ui_describe_all exposes the AXLabel of each element, unlabeled controls stand out immediately. This turns a tedious manual audit into one prompt — and it’s a use case the keyboard- and-screen-reader crowd genuinely benefits from.

Recipe 4 — React Native / Expo iteration loop

For RN and Expo apps, pair this server with a fast refresh dev build. The agent edits a component, the bundler hot-reloads, and the agent taps through the changed screen to confirm the fix landed — all in one turn. One developer even demoed Claude Code driving an iOS simulator and an Android emulator side by side; the simulator half is exactly this server’s job.

Common mistakes

Community signal

The clearest demand signal is the volume of developers trying to wire Claude Code into a mobile simulator loop — often before discovering a purpose-built server exists.

On the React Native side, a widely-upvoted thread showed Claude Code driving an iOS simulator and an Android emulator at the same time — the simulator half is this server’s territory, and the reception was strongly positive.

The contrarian view comes from developers who’ve gone deeper. A separate r/iOSProgramming project, “Pepper,” argues that simulator-control MCPs only see the UI surface — and that real agent-driven iOS work wants runtime inspection: live view hierarchies, network traffic, heap, and variable mutation inside the app process. It’s a fair critique. iOS Simulator MCP is deliberately scoped to the simulator’s external controls and the accessibility tree; if you need to reach inside the running process, that’s a different and heavier tool.

iOS Simulator MCP vs XcodeBuildMCP

These two come up together constantly, and they’re complementary, not competing. The split is build vs. interact.

Many teams install both: XcodeBuildMCP builds and launches, iOS Simulator MCP exercises the result. We wrote a full XcodeBuildMCP complete guide if the build side is what you need. For everything else in the catalog, browse all MCP servers.

The verdict

Frequently asked questions

Glossary

MCP

Model Context Protocol — the JSON-RPC wire format that lets any LLM client talk to any tool server.

IDB

Facebook’s iOS Development Bridge — the CLI this server uses for UI interaction and accessibility inspection. Must be on your PATH.

simctl

Xcode’s simulator control CLI. Ships with Xcode; handles screenshots, video recording, and device lookup here.

Accessibility tree

The structured representation of on-screen elements and their labels — how the agent reads the screen without OCR.

AXLabel

The accessibility label on an element. The agent matches controls by this string via ui_find_element.

UDID

Unique device identifier for a simulator instance. Tools accept an optional udid; the agent finds the default via get_booted_sim_id.

stdio transport

The MCP transport where the client spawns the server as a child process and talks over stdin/stdout. This server is stdio-only — no remote URL.

Command injection (CWE-78)

A flaw where untrusted input is concatenated into a shell command, letting an attacker run arbitrary commands. The pre-1.3.3 bug here; fixed in v1.3.3.

Sources & links

Primary

• Repository & README: github.com/joshuayoes/ios-simulator-mcp (MIT, by Joshua Yoes)
• npm package: ios-simulator-mcp
• Security advisory: GHSA-6f6r-m9pv-67jw / CVE-2025-52573
• Facebook IDB: fbidb.io
• Anthropic, Claude Code best practices (mentions this server): anthropic.com/engineering/claude-code-best-practices

Community

• r/reactnative — Claude Code controlling iOS simulator & Android emulator
• r/ClaudeCowork — How-to: iOS app dev — testing in simulator
• r/iOSProgramming — Pepper, an MCP for iOS runtime inspection (contrarian view)
• r/ClaudeAI — Complete Claude Code setup guide for iOS/Swift development

Internal

• iOS Simulator on MCP.Directory
• XcodeBuildMCP complete guide
• What is MCP?
• Claude Code MCP setup