Gemini CLI and the iOS simulator: MCP setup

Gemini CLI can change your SwiftUI code from the terminal. With mobster mcp added, it can also run the app on a headless iOS simulator Mobster manages, read each screen as a list of controls by name, tap and type, and get a verdict of passed or failed from assertions on the accessibility tree. The same server can drive a real iPhone over USB.

You need an Apple silicon Mac with macOS 15 or later and Xcode with an iOS Simulator runtime. A real iPhone also needs Developer Mode and the WebDriverAgent runner, set up in Mobster for Mac or with mobster serve --manage-device (Device setup). Gemini CLI’s site notes that unpaid-tier and Google One users moved to Antigravity CLI on 18 June 2026; this page covers Gemini CLI’s own configuration.

Install Mobster CLI

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

or

$ brew install radishsoftware/tap/mobster

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

mobster sim doctor --fix creates Mobster’s simulator, boots it headless and builds WebDriverAgent, once per Xcode version.

Add the server

$ gemini mcp add -s user mobster mobster mcp

The first mobster is the server’s name, and mobster mcp is the command. Without -s user, gemini mcp add writes to the project’s .gemini/settings.json and the server exists only in that project. The user-scope entry lands in ~/.gemini/settings.json:

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

The default timeout is 600,000 ms, ten minutes, which covers every Mobster call: each returns within 45 seconds and wait within 50. Gemini CLI’s docs call the field a request timeout in one place and the --timeout flag a connection timeout in another; the default is long enough under either reading, so leave it unset.

Key-less checks need no key: Gemini drives with its own model, and Mobster judges. For Smart, where Mobster runs the steps itself on your OpenAI or Anthropic key, pass an env file. Gemini CLI strips environment variables whose names contain KEY, TOKEN, SECRET and similar from a server’s environment unless you list them in its env, so a key exported in your shell won’t reach Mobster. --env-file has Mobster read the file itself:

"args": ["mcp", "--env-file", "~/.config/mobster/agent.env"]

Mobster expands the ~. The file holds OPENAI_API_KEY=… or ANTHROPIC_API_KEY=… and should be readable only by you.

Check it’s connected

Gemini CLI tests and connects stdio servers only in a trusted folder. In your project:

$ gemini trust
$ gemini mcp list

Inside a session, /mcp shows each server as connected or disconnected, with its tools. Then ask:

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

A first check: catch a planted bug

Daybreak, the sample app in the CLI’s repository, ships a script that plants real bugs in its source. Drop one plan from the paywall and rebuild:

$ cd examples/ios/Daybreak
$ scripts/plant-bug.sh missing-plan      # ForEach(Plan.all) becomes ForEach(Plan.all.prefix(2))
$ xcodebuild -project Daybreak.xcodeproj -scheme Daybreak -destination 'generic/platform=iOS Simulator' \
  -derivedDataPath .build CODE_SIGNING_ALLOWED=NO build

Then ask Gemini:

Use mobster to verify Daybreak's paywall at daybreak://paywall: "Choose your plan" on screen,
three elements whose id starts with plan_, and Annual's value "$39.99 / year".

Gemini calls verify_start with the absolute app_path, the deep link and those expectations, reads the screen, and calls verify_finish. The verdict is failed, and the result names what it found. Daybreak’s paywall check, run from the terminal against the same bug on 28 Sep 2026, printed these two lines among its results:

✗ count id=/^plan_/ == 3: found 2: plan_weekly, plan_monthly
✗ value id=plan_annual == "$39.99 / year": not found; closest: "plan_monthly"

Ask Gemini to find the cause and fix it, then verify again. scripts/plant-bug.sh missing-plan --undo puts the line back if you’d rather do it yourself. The report path in the result opens a one-file HTML report with the two plan cards outlined in red.

Put the rule in GEMINI.md

Gemini CLI loads GEMINI.md files as context: ~/.gemini/GEMINI.md for every project, and GEMINI.md in your workspace. Add this to the project’s file, with your scheme and app names:

## 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.

Use a real iPhone

list_devices shows each device Mobster can use. With a USB iPhone’s name as device and no run_id, the phone tools (screen, tap, type_text, swipe, alert, open_url, launch_app and home) act on the phone directly. Mobster holds the phone’s lock until stop with the device, or 90 idle seconds.

Gemini CLI asks before a tool call, with four answers: proceed once, always allow this tool, always allow this server, or cancel. On a server that can reach your phone, “always allow this server” covers tap and type_text on the iPhone too, and so does "trust": true in the settings. Your approval covers a tool, not a device, so keep the server to the phones you mean:

"args": ["mcp", "--allow-device", "Test iPhone"]

Any other real device is listed as not_allowed and refused. excludeTools in the server’s settings hides tools you never want Gemini to call, such as install_app. Mobster’s MCP annotations mark status, screen, list_devices, wait, wait_for, read_notifications and unlock_status as read-only, and its instructions tell Gemini to ask you before anything that sends, buys, posts or deletes on a real iPhone. A locked phone stops the call at once, and Mobster never enters a passcode.

Troubleshooting

The MCP reference has every tool and argument.