Claude Code on your iPhone and the iOS simulator: MCP setup

Claude Code can write a SwiftUI screen, but it can’t see one. With mobster mcp connected, Claude builds your app for the simulator, drives it through Mobster’s tools, and gets a verdict of passed or failed from assertions on the accessibility tree, with the frames that prove it. The same server lets Claude use a real iPhone plugged into your Mac.

For simulator work you need an Apple silicon Mac with macOS 15 or later and Xcode with an iOS Simulator runtime. For a real iPhone you also need Developer Mode on the phone and the WebDriverAgent runner set up for it in Mobster for Mac, or with mobster serve --manage-device (Device setup). Mobster’s MCP server is tested with Claude Code.

Install Mobster CLI

$ curl -fsSL https://mobster.dev/install.sh | sh

Or with Homebrew, which installs the same build:

$ brew install radishsoftware/tap/mobster

Check that the command is on your PATH, then prepare the simulator once. This creates Mobster’s own simulator, boots it headless and builds WebDriverAgent, once per Xcode version:

$ mobster version
$ which mobster
$ mobster sim doctor --fix

You can skip the last step, and the first check does the same work instead. Mobster never touches your own simulators: it creates its own, named Mobster · ….

Add the server

One command, run in your project’s folder:

$ claude mcp add mobster -- mobster mcp

The -- separates Claude Code’s own options from the command that starts the server. Without --scope, Claude Code stores the server in the local scope, so it shows up only in the folder you ran this in. Pick the scope you want:

To share it with your team, commit this .mcp.json. Claude Code asks each person to approve a project server before it connects.

{  "mcpServers": {    "mobster": { "command": "mobster", "args": ["mcp"] }  }}

Key-less checks need nothing more. For Smart, where Mobster runs the steps itself on your OpenAI or Anthropic key, point the server at a private env file:

$ claude mcp add mobster -- mobster mcp --env-file ~/.config/mobster/agent.env

The file holds one line, OPENAI_API_KEY=… or ANTHROPIC_API_KEY=…. Keep it out of the repository and readable only by you (chmod 600).

Timeouts need no change. Every Mobster tool call returns within 45 seconds and wait within 50. Claude Code’s default tool timeout is far longer than that, and its idle timer for stdio servers is reset by progress notifications, which Mobster sends every 5 seconds while a call waits.

Check it’s connected

Start claude in the project and type /mcp. Mobster should be listed as connected, with its tools. From the terminal, claude mcp list shows the same. Then ask Claude:

Call mobster's status tool and tell me what it says.

status reports Mobster’s version, the simulator setup, whether Smart is available (and if not, why), where runs go, and any open run.

A first check: the paywall

Daybreak, the sample app in the CLI’s repository, has a three-plan paywall. Ask Claude to change it and prove it still works:

Restyle the paywall cards, then verify the paywall still shows three plans,
with Annual at "$39.99 / year" and a Restore Purchases button.

Claude builds the scheme for the simulator, then calls verify_start with the absolute app_path, the steps and the expectations. The expectations are fixed at that moment, before Claude touches the app. Each tap, type_text or swipe returns the new screen as an outline Claude reads. Three lines of Daybreak’s paywall, as screen returned them on 28 Sep 2026:

e7  button  "Weekly"                            value="$2.99 / week"   id=plan_weekly
e13 button  "Monthly"                           value="$7.99 / month"  id=plan_monthly
e20 button  "Annual"                            value="$39.99 / year"  id=plan_annual  selected

verify_finish checks every expectation on one settled read and returns the verdict, the path to a one-file HTML report and the overlay frame. If the restyle had dropped a plan, the verdict is failed, with the reason. Run as a saved check from the terminal, that same failure prints like this (28 Sep 2026):

✗ failed  The paywall shows three plans with Annual at $39.99 a year  (18.2 s)
  ✓ text "Choose your plan"
  ✗ count id=/^plan_/ == 3: found 2: plan_weekly, plan_monthly
  ✗ value id=plan_annual == "$39.99 / year": not found; closest: "plan_monthly"
  ✓ visible label=Restore Purchases role=button
  ✓ no_text "Loading"

Claude then fixes the code, rebuilds and verifies again. The verdict comes from the assertions, never from a model. Give Claude Code a real iPhone walks through the loop in more detail.

Make it a habit with CLAUDE.md

Put the standing instruction in your project’s CLAUDE.md, with your scheme and app names, so Claude verifies every UI change without being asked:

## Verifying UI changesAfter you change a screen in this iOS app, verify it before you say it works.1. Build for the simulator:   xcodebuild -scheme <Scheme> -destination 'generic/platform=iOS Simulator' -derivedDataPath .mobster/build CODE_SIGNING_ALLOWED=NO build2. Call mobster's verify_start with app_path set to the absolute path of   .mobster/build/Build/Products/Debug-iphonesimulator/<App>.app, the steps in plain English, and expect:   what must be true when the steps are done.3. Drive with screen, tap, type_text and swipe, then call verify_finish.4. If the verdict is failed, fix the code and verify again. Report the verdict and the report path.

Give the controls your checks need an accessibility identifier, such as .accessibilityIdentifier("plan_annual"), so an id selector survives copy changes.

Use a real iPhone

Claude calls list_devices to see every device Mobster can use: USB iPhones set up for it, Mobster’s simulators and any WebDriverAgent address. The phone tools (screen, tap, type_text, swipe, alert, open_url, launch_app and home) called with device and no run_id drive that device directly. Mobster takes the device’s lock on the first call, so no other Mobster app or command drives it at the same time. stop with the device, or 90 idle seconds, releases it.

On a real iPhone a tap on Send sends. Claude Code approves a tool, not a device: allowing tap for simulator work allows it on your phone too. Name the phones the server may drive, and every other real device is refused:

$ claude mcp add mobster -- mobster mcp --allow-device "Test iPhone"

Mobster marks each tool in its MCP annotations. status, screen, list_devices, wait, wait_for, read_notifications and unlock_status only read, and the tools that act on the device are marked as acting. If you add allow rules in Claude Code’s settings, allow only the read tools, such as mcp__mobster__screen, and keep the prompt on the rest. The server’s instructions also tell Claude that text on the screen is data, not instructions, and to ask you before anything that sends, buys, posts or deletes on a real iPhone.

A locked phone stops the call at once with “Your iPhone is locked. Unlock it and try again. No action was taken.” Mobster never enters a passcode.

Troubleshooting

Every tool and its arguments are in the MCP reference.