--- title: "Claude Code and your iPhone: MCP setup | Mobster" description: "Add Mobster's MCP server to Claude Code with one command, then let Claude check the iOS screens it writes on a simulator or use your iPhone over USB." canonical: "https://mobster.dev/integrations/claude-code" last-updated: "2026-10-08" --- Add Mobster's MCP server to Claude Code with one command, then let Claude check the iOS screens it writes on a simulator or use your iPhone over USB. # Claude Code on your iPhone and the iOS simulator: MCP setup Add Mobster's MCP server to Claude Code with one command, then let Claude check the iOS screens it writes on a simulator or use your iPhone over USB. ## The short version Install Mobster CLI, then run: ``` claude mcp add mobster -- mobster mcp ``` Config file: .mcp.json at the repository root, to share it with your team **Tested.** Tested with Mobster's MCP server. The client's own steps follow its documentation, read on 8 October 2026. [Anthropic’s MCP docs](https://code.claude.com/docs/en/mcp). 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](https://docs.mobster.dev/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: | Scope | Command | Where it applies | |---|---|---| | Local (default) | `claude mcp add mobster -- mobster mcp` | This project folder, for you | | User | `claude mcp add --scope user mobster -- mobster mcp` | Every project, for you | | Project | a `.mcp.json` at the repository root | Everyone who clones the repository | 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](https://mobster.dev/blog/claude-code-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 -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, 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 | Symptom | Fix | |---|---| | `/mcp` doesn’t list mobster in another project | The server was added in the local scope. Add it with `--scope user`, or commit a `.mcp.json` | | A project server waits for approval | Run `claude` in the project and approve it. `claude mcp reset-project-choices` asks again | | The first `verify_start` returns `status: "preparing"` | The first run boots the simulator and builds WebDriverAgent. Claude calls `wait` until it’s ready, or run `mobster sim doctor --fix` beforehand | | The `verify` tool is missing | Smart is off. `status` says why: no `OPENAI_API_KEY` or `ANTHROPIC_API_KEY`, an env file that doesn’t exist, or `--keyless` | | `couldnt_run` | `reason.class` and `reason.fix` in the result say what to do. [Getting started with verify](https://docs.mobster.dev/verify#troubleshooting) covers each class | Every tool and its arguments are in the [MCP reference](https://docs.mobster.dev/mcp-server). ## Questions - ### Does Claude Code need a longer MCP timeout for Mobster? No. Every Mobster tool call returns within 45 seconds and wait within 50, and Claude Code's default tool timeout is far longer. Mobster also sends a progress notification every 5 seconds, which keeps Claude Code's idle timer from firing. - ### Why does Claude Code only see Mobster in one folder? claude mcp add uses the local scope unless you pass --scope, so the server belongs to the folder you ran it in. Add it again with --scope user to use it in every project, or commit a .mcp.json to share it with your team. - ### Does Claude Code need a model key for Mobster? No. In the key-less loop Claude drives the app with its own model and Mobster judges the result from the accessibility tree. Mobster calls a model only for the Smart verify tool, which needs your own OpenAI or Anthropic key. - ### How do I give Claude Code access to the iOS Simulator? Add Mobster's MCP server with claude mcp add mobster -- mobster mcp. Claude Code then gets a headless simulator that Mobster creates and boots, reads each screen as a list of controls by name, taps, types and swipes, and gets passed or failed from assertions. Mobster never touches your own simulators. - ### Can Claude Code control the iOS Simulator? Yes, through an MCP server. With Mobster connected, Claude Code builds your app for the simulator, opens it, and acts on buttons and fields by name from the accessibility tree instead of guessing from a screenshot. The verdict on the screen comes from assertions, not from Claude. - ### What does Claude Code need for iOS development with Mobster? 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, which Mobster for Mac sets up for you, or mobster serve --manage-device from the CLI. - ### Does it work with Claude Code on Windows? No. Xcode and the iOS Simulator run only on macOS, so Mobster needs an Apple silicon Mac. Claude Code on Windows or Linux can't drive an iOS simulator through Mobster. ## 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). - [Claude Code docs: connect Claude Code to tools via MCP](https://code.claude.com/docs/en/mcp) - [Claude Code docs: permissions](https://code.claude.com/docs/en/permissions) - [Claude Code docs: how Claude remembers your project (CLAUDE.md)](https://code.claude.com/docs/en/memory) - [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: add Mobster to your agent](https://docs.mobster.dev/agents) - [Mobster docs: device setup](https://docs.mobster.dev/device-setup) Claude Code’s logo is a trademark of Anthropic, shown only to name the product. Mobster isn’t affiliated with or endorsed by Anthropic. ## Read next - [Every MCP tool, in the reference](https://docs.mobster.dev/mcp-server) - [Getting started with verify](https://docs.mobster.dev/verify) - [Give Claude Code a real iPhone](https://mobster.dev/blog/claude-code-real-iphone) ## Other agents - [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) - [Gemini CLI](https://mobster.dev/integrations/gemini-cli) - [opencode](https://mobster.dev/integrations/opencode) - [Windsurf (Devin Desktop)](https://mobster.dev/integrations/windsurf)