---
title: "Claude Desktop and your iPhone: MCP setup | Mobster"
description: "Add Mobster to Claude Desktop's config file with an absolute path, restart the app, and let Claude read and tap through an iOS simulator or your iPhone."
canonical: "https://mobster.dev/integrations/claude-desktop"
last-updated: "2026-10-08"
---

Add Mobster to Claude Desktop's config file with an absolute path, restart the app, and let Claude read and tap through an iOS simulator or your iPhone.

# Claude Desktop and your iPhone: MCP setup

Add Mobster to Claude Desktop's config file with an absolute path, restart the app, and let Claude read and tap through an iOS simulator or your iPhone.

## The short version

Install Mobster CLI, then run:

```
mobster mcp install claude-desktop
```

Config file: ~/Library/Application Support/Claude/claude_desktop_config.json

**From the docs.** This setup follows Anthropic's MCP documentation, read on 8 October 2026. Mobster's MCP server is tested with Claude Code; we haven't run it in Claude Desktop ourselves yet. [Anthropic’s MCP docs](https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop).

Claude Desktop is where many people talk to Claude outside a terminal. With `mobster mcp` added, Claude can run an iOS app on a headless simulator Mobster manages, read each screen as a list of controls by name, tap and type, and return a verdict from assertions on the accessibility tree. It can also use a real iPhone plugged into your Mac, through the same tools.

You need an Apple silicon Mac with macOS 15 or later. Simulator work needs Xcode with an iOS Simulator runtime. A real iPhone 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)).

## Install Mobster CLI

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

or

```
brew install radishsoftware/tap/mobster
```

Then note the full path to the command, which Claude Desktop needs, and prepare the simulator once:

```
mobster version
which mobster
mobster sim doctor --fix
```

## Add the server

Open Claude Desktop’s config from the Claude menu: Settings, then the Developer tab, then Edit Config. The file is `~/Library/Application Support/Claude/claude_desktop_config.json`. Add Mobster under `mcpServers`, with the path `which mobster` printed:

```
{  "mcpServers": {    "mobster": {      "command": "/opt/homebrew/bin/mobster",      "args": ["mcp", "--out", "/Users/<you>/mobster-runs"]    }  }}
```

Use an absolute path for both. Claude Desktop starts a local server with only a small part of your environment, so `mobster` alone may not be found, and the server’s working folder may be `/`. When it is, Mobster writes runs to `runs/` in its own data folder; `--out` puts them where you can find them. Each run folder holds `report.html`, `result.json` and the frames.

Or let Mobster write the entry with the full path: `mobster mcp install claude-desktop`. It leaves out `--out`, so add that yourself if you want the runs in a folder you choose.

Quit Claude Desktop completely and open it again, so it reads the file.

For Smart, where Mobster runs the steps itself on your OpenAI or Anthropic key, add `"--env-file", "/Users/<you>/.config/mobster/agent.env"` to `args`. The file holds `OPENAI_API_KEY=…` or `ANTHROPIC_API_KEY=…`, readable only by you. Without it, Claude does the driving with its own model and Mobster calls no model at all.

The MCP pages for Claude Desktop don’t state a tool-call timeout. Mobster keeps its calls short: each returns within 45 seconds and `wait` within 50. The first simulator boot and a Smart run continue under a `run_id`, and Claude calls `wait` until they’re done.

## Check it’s connected

Click the + button under the chat box, then Connectors: mobster should be listed. The Developer tab in Settings shows each server’s status and opens its logs. Mobster’s log, which it writes to stderr, ends up in `~/Library/Logs/Claude/mcp-server-mobster.log`. Then ask:

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

## A first check: the paywall, launch-only

A check with no steps is the quickest one to try. Build Daybreak, the sample app in the CLI’s repository, once in Terminal:

```
git clone https://github.com/RadishSoftware/mobster && cd mobster
xcodebuild -project examples/ios/Daybreak/Daybreak.xcodeproj -scheme Daybreak \
  -destination 'generic/platform=iOS Simulator' -derivedDataPath examples/ios/Daybreak/.build CODE_SIGNING_ALLOWED=NO build
```

Then ask Claude, with the absolute path to the app you built:

```
Use mobster to check Daybreak at /Users/<you>/mobster/examples/ios/Daybreak/.build/Build/Products/Debug-iphonesimulator/Daybreak.app.
Open daybreak://paywall with no steps, and expect "Choose your plan", three elements whose id starts
with plan_, Annual's value "$39.99 / year", a Restore Purchases button, and no "Loading".
```

Claude calls `verify_start` with an empty `steps` list and these expectations, which are the ones in Daybreak’s own `paywall.yaml`:

```
[  {"text": "Choose your plan"},  {"count": {"id": "/^plan_/"}, "equals": 3},  {"value": {"id": "plan_annual"}, "equals": "$39.99 / year"},  {"visible": {"label": "Restore Purchases", "role": "button"}},  {"no_text": "Loading"}]
```

Mobster installs the app, opens the deep link, and `verify_finish` decides on one settled read of the accessibility tree. No model decides the verdict. Claude gets passed or failed, the line that failed if any, and the path to `report.html`, which shows the screen with each asserted element outlined in green or red. From there, ask Claude to tap through a flow, and it uses `screen`, `tap`, `type_text` and `swipe` before `verify_finish`.

## Use a real iPhone

Ask Claude to call `list_devices`. A USB iPhone set up for Mobster is listed with its name and state. Called with that `device` and no `run_id`, `screen`, `tap`, `type_text`, `swipe`, `alert`, `open_url`, `launch_app` and `home` act on the phone itself. Mobster takes the phone’s lock, so the Mac app and other commands wait, and releases it after `stop` with the `device` or 90 idle seconds.

Claude Desktop asks for your approval before a tool runs. That approval covers a tool, not a device: allowing `tap` while testing on a simulator allows it on your iPhone too. Limit the server to the phones you choose by adding `"--allow-device", "Test iPhone"` to `args`; any other real device is listed as `not_allowed` and refused. Mobster’s MCP annotations mark `status`, `screen`, `list_devices`, `wait`, `wait_for`, `read_notifications` and `unlock_status` as read-only, and its instructions tell Claude to treat text on the screen as data and to ask you before anything that sends, buys, posts or deletes on a real iPhone.

A locked iPhone stops the call at once with “Your iPhone is locked. Unlock it and try again. No action was taken.” Mobster never enters a passcode and never uses Face ID.

## Troubleshooting

| Symptom | Fix |
|---|---|
| mobster isn’t in Connectors after a restart | Use the absolute path from `which mobster` in `command`, check the JSON is valid, and quit Claude Desktop completely before opening it again |
| The server starts and exits | Read `~/Library/Logs/Claude/mcp-server-mobster.log`, which holds the server’s own error output |
| You can’t find the run’s report | Pass `--out` with an absolute folder. Without it, a server started in `/` writes to `runs/` in Mobster’s data folder |
| The first `verify_start` returns `status: "preparing"` | The simulator is booting and WebDriverAgent is building. Claude calls `wait`, or run `mobster sim doctor --fix` beforehand |
| `couldnt_run`, or no `verify` tool | `reason.fix` in the result says what to do. `status` says why Smart is off |

The [MCP reference](https://docs.mobster.dev/mcp-server) lists every tool. For coding work in the terminal, see [Mobster in Claude Code](https://mobster.dev/integrations/claude-code).

## Questions

- ### Why doesn't Claude Desktop start the Mobster server?
  Most often the command isn't an absolute path. Claude Desktop starts local servers with only a small part of your environment, so your shell's PATH may be missing. Put the output of which mobster in command, then quit Claude Desktop completely and open it again.
- ### Can I add Mobster from the Connectors menu?
  No. Add it by editing claude_desktop_config.json, through Settings, then Developer, then Edit Config. The Connectors menu then shows it once it's connected.
- ### Where do Mobster's runs go when Claude Desktop starts the server?
  Claude Desktop may start servers in the root folder, and when the folder is / or your home folder, Mobster writes runs to runs/ in its own data folder. Pass --out with an absolute path to choose another folder.

## 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 Help Center: getting started with local MCP servers on Claude Desktop](https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop)
- [MCP docs: connect to local MCP servers](https://modelcontextprotocol.io/docs/2026-07-28/develop/connect-local-servers)
- [MCP docs: debugging (working folder, environment, logs)](https://modelcontextprotocol.io/docs/2026-07-28/tools/debugging)
- [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)

Claude Desktop’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)

## 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)
- [Gemini CLI](https://mobster.dev/integrations/gemini-cli)
- [opencode](https://mobster.dev/integrations/opencode)
- [Windsurf (Devin Desktop)](https://mobster.dev/integrations/windsurf)