> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mobster.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# mobster mcp

> Let your coding agent use the phone and check your app.

Serve Mobster as an MCP server on stdio, so your coding agent can launch and check an iOS app on a simulator: it starts a check with verify\_start, drives the app with screen, tap, type\_text and swipe, and gets the verdict from verify\_finish.

## Usage

```text theme={"theme":"css-variables"}
mobster mcp [options] [<command>]
```

## Options

| Name | Default | Description |
| - | - | - |
| `--env-file PATH` | `$MOBSTER_ENV_FILE` | load KEY=VALUE lines; OPENAI\_API\_KEY or ANTHROPIC\_API\_KEY turns on smart in verify\_start; variables already set win |
| `--keyless` | off | never offer smart in verify\_start, even with an OpenAI or Anthropic key: the coding agent drives |
| `--device NAME` | iPhone 17 Pro | the device for runs and phone tools that don't name one: an id, UDID or name from `mobster devices`, or a simulator device type |
| `--allow-device NAME` | none | drive only this real iPhone (id, UDID or name), never another; repeatable. Without it every set-up device is allowed; simulators always are |
| `--allow-testflight BUNDLE` | none | let run\_tests with pr drive this app's TestFlight build on an `--allow-device` iPhone as your own app; repeatable |
| `--allow-files` | off | offer the file tools (put\_file, get\_file, list\_files, and send\_media, which adds to Photos) when this build has them; off by default |
| `--allow-photos` | off | offer pull\_media, which copies the newest photos and recordings from an iPhone's camera roll to this Mac; off by default |
| `--runtime NAME` | the newest installed | the iOS runtime for runs that don't name one, such as "iOS 26.4" |
| `--out DIR` | `$MOBSTER_RUNS_DIR`, else ./.mobster/runs | where runs go |
| `--log FILE` | none | also append the server's log to FILE (it never holds keys or long typed text) |

```text theme={"theme":"css-variables"}
examples:
  mobster mcp install --all      add Mobster to Claude Code, Codex, Cursor and the others found here
  mobster mcp clients            which agent clients are here, and which run Mobster
  mobster mcp doctor             start the server as a client would and call status
```

## Commands

| Command | What it does |
| - | - |
| [`mobster mcp install`](#mobster-mcp-install) | add Mobster's server to Claude Code, Codex, Cursor and others |
| [`mobster mcp clients`](#mobster-mcp-clients) | list the agent clients found here and whether Mobster is set up |
| [`mobster mcp doctor`](#mobster-mcp-doctor) | start the server as a client would, list its tools and call status |

## `mobster mcp install`

Add Mobster's MCP server to your agents' configs: Claude Code, Codex, Cursor, VS Code, Claude Desktop, opencode, Gemini CLI, Windsurf, Copilot CLI, Zed, Goose, Amp, Cline, oh-my-pi (omp) and the agents inside Xcode. It writes the absolute path of this mobster, because apps opened from the Dock don't see your shell's PATH. Claude Code and Codex are set up with their own `mcp add` commands; the rest by editing the file, keeping its comments and formatting, with a copy of the old file beside it (.mobster-backup). Reinstalling keeps each client's server options and environment. Explicit options replace their own group; `--reset-server-options` starts fresh. Smart's key stays in `--env-file`.

### Arguments and options

| Name | Default | Description |
| - | - | - |
| `[CLIENT ...]` | none | the clients to set up, by name (see `mobster mcp clients`) |
| `--all` | off | every client found on this Mac |
| `--project DIR` | none | write the project's config in DIR (such as .cursor/mcp.json) instead of yours |
| `--allow-device NAME` | none | the server drives only this real iPhone; repeatable |
| `--allow-testflight BUNDLE` | none | run\_tests with pr may drive this app's TestFlight build on an allowed iPhone; repeatable |
| `--env-file PATH` | none | the server loads this file (OPENAI\_API\_KEY or ANTHROPIC\_API\_KEY for Smart); it must be readable by you only (chmod 600) |
| `--reset-server-options` | off | replace the saved server options and environment instead of keeping them |
| `--with-skill` | off | also copy the ios-testing skill into each client's skills folder; with `--remove`, delete it |
| `--rules DIR` | none | also write Mobster's rules for agents in DIR: a block in AGENTS.md, and .cursor/rules/mobster.mdc for Cursor |
| `--with-xcode-tools` | off | also add Xcode's own tools (xcrun mcpbridge, Xcode 26.3 or later) to Claude Code and Codex |
| `--dry-run` | off | show what would change and write nothing |
| `--remove` | off | take Mobster out of the clients' configs instead; the skill stays unless you add `--with-skill` |
| `--json` | off | print the result as JSON |

```text theme={"theme":"css-variables"}
examples:
  mobster mcp install --all                      every client found on this Mac
  mobster mcp install claude-code cursor --with-skill
  mobster mcp install codex --env-file ~/.config/mobster/agent.env
  mobster mcp install --all --allow-device "Test iPhone"
  mobster mcp install cursor --project .         this repository's .cursor/mcp.json
  mobster mcp install cursor --with-skill --rules .   this repository's AGENTS.md and .cursor/rules
  mobster mcp install xcode                      the agents inside Xcode
  mobster mcp install claude-code codex --with-xcode-tools
  mobster mcp install --all --remove --with-skill

clients: claude-code, codex, cursor, vscode, claude-desktop, opencode, gemini, windsurf, copilot-cli, zed, goose, amp, cline, omp, xcode
```

## `mobster mcp clients`

List the agent clients Mobster can set up, whether each is installed on this Mac, and whether its config runs Mobster's server.

### Options

| Name | Default | Description |
| - | - | - |
| `--project DIR` | none | look at the project's configs in DIR |
| `--json` | off | print the list as JSON |

## `mobster mcp doctor`

Start Mobster's MCP server the way an app opened from the Dock would (its absolute path, launchd's PATH, the home folder), send initialize, list the tools and call status, with the time each step took. Then check that every client's entry runs a mobster that exists.

### Options

| Name | Default | Description |
| - | - | - |
| `--env-file PATH` | none | start the server with this env file, as install would |
| `--json` | off | print the report as JSON |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.