---
title: "Gemini CLI and the iOS simulator: MCP setup | Mobster"
description: "Add Mobster to Gemini CLI with gemini mcp add at user scope, trust the folder, and let Gemini check your iOS app on a simulator with verdicts from assertions."
canonical: "https://mobster.dev/integrations/gemini-cli"
last-updated: "2026-10-08"
---

Add Mobster to Gemini CLI with gemini mcp add at user scope, trust the folder, and let Gemini check your iOS app on a simulator with verdicts from assertions.

# Gemini CLI and the iOS simulator: MCP setup

Add Mobster to Gemini CLI with gemini mcp add at user scope, trust the folder, and let Gemini check your iOS app on a simulator with verdicts from assertions.

## The short version

Install Mobster CLI, then run:

```
gemini mcp add -s user mobster mobster mcp
```

Config file: ~/.gemini/settings.json

**From the docs.** This setup follows Google's MCP documentation, read on 8 October 2026. Mobster's MCP server is tested with Claude Code; we haven't run it in Gemini CLI ourselves yet. [Google’s MCP docs](https://geminicli.com/docs/tools/mcp-server/).

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](https://docs.mobster.dev/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

| Symptom | Fix |
|---|---|
| `/mcp` shows mobster disconnected | Run `gemini trust` in the folder. Stdio servers connect only in trusted folders |
| mobster is missing in another project | It was added at project scope. Add it again with `-s user` |
| Smart is off although your key is exported | Gemini CLI removed the variable. Pass `--env-file`, or set the key in the server’s `env` |
| The first `verify_start` returns `status: "preparing"` | The simulator is booting and WebDriverAgent is building. Gemini calls `wait`, or run `mobster sim doctor --fix` first |
| `couldnt_run` | `reason.class` and `reason.fix` in the result say what to do ([Checks](https://docs.mobster.dev/checks)) |

The [MCP reference](https://docs.mobster.dev/mcp-server) has every tool and argument.

## Questions

- ### Why does Gemini CLI show Mobster as disconnected?
  Gemini CLI connects stdio servers only in a trusted folder. Run gemini trust in your project, then check /mcp again. Also check the scope, since gemini mcp add writes to the project's settings unless you pass -s user.
- ### How do I give Mobster a model key under Gemini CLI?
  Use Mobster's --env-file argument. Gemini CLI removes environment variables whose names contain KEY, TOKEN or SECRET before it starts a server, unless you set them in the server's env, while --env-file has Mobster read the key from a file itself.
- ### Should I set trust to true for Mobster?
  Not if the server can reach your iPhone. trust true skips every confirmation for the server, including taps and typing on a real phone. Leave it off and approve tools as they come.

## Sources

We read each of these on 8 October 2026. Reviewed by Andy Guo on 8 October 2026. Corrections are welcome at the [GitHub repo](https://github.com/RadishSoftware/mobster/issues).

- [Gemini CLI docs: MCP servers](https://geminicli.com/docs/tools/mcp-server/)
- [Gemini CLI docs: trusted folders](https://geminicli.com/docs/cli/trusted-folders/)
- [Gemini CLI docs: project context (GEMINI.md)](https://geminicli.com/docs/cli/gemini-md/)
- [MCP specification: ToolAnnotations (readOnlyHint)](https://modelcontextprotocol.io/specification/2025-11-25/schema)
- [Apple: enabling Developer Mode on a device](https://developer.apple.com/documentation/xcode/enabling-developer-mode-on-a-device)
- [Mobster docs: MCP server](https://docs.mobster.dev/mcp-server)
- [Mobster docs: checks](https://docs.mobster.dev/checks)
- [Mobster docs: device setup](https://docs.mobster.dev/device-setup)

Gemini CLI’s logo is a trademark of Google, shown only to name the product. Mobster isn’t affiliated with or endorsed by Google.

## Read next

- [Every MCP tool, in the reference](https://docs.mobster.dev/mcp-server)
- [Getting started with verify](https://docs.mobster.dev/verify)

## Other agents

- [Claude Code](https://mobster.dev/integrations/claude-code)
- [Codex](https://mobster.dev/integrations/codex)
- [Cursor](https://mobster.dev/integrations/cursor)
- [VS Code](https://mobster.dev/integrations/vs-code)
- [Claude Desktop](https://mobster.dev/integrations/claude-desktop)
- [opencode](https://mobster.dev/integrations/opencode)
- [Windsurf (Devin Desktop)](https://mobster.dev/integrations/windsurf)