mobster mcp

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

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)

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`	add Mobster’s server to Claude Code, Codex, Cursor and others
`mobster mcp clients`	list the agent clients found here and whether Mobster is set up
`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

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

CLI

MCP

Settings and errors

Inside Mobster

Usage

Options

Commands

`mobster mcp install`

Arguments and options

`mobster mcp clients`

Options

`mobster mcp doctor`

Options

​Usage

​Options

​Commands

​mobster mcp install

​Arguments and options

​mobster mcp clients

​Options

​mobster mcp doctor

​Options

Usage

Options

Commands

`mobster mcp install`

Arguments and options

`mobster mcp clients`

Options

`mobster mcp doctor`

Options