# XcodeBuildMCP setup for Claude Code and Codex

Canonical URL: https://macswarm.com/docs/xcodebuildmcp-on-a-cloud-mac/
Last reviewed: 2026-10-26

> XcodeBuildMCP, now MobileBuildMCP, lets Claude Code and Codex build, run, test and screenshot iOS apps. Setup for both, the local limits, and Pods.

To add XcodeBuildMCP to Claude Code or Codex, register the mobilebuildmcp MCP server on a Mac with Xcode installed. XcodeBuildMCP is now named MobileBuildMCP. The commands below configure each client; Macswarm Pods already include the tooling.

## How do Claude Code and Codex connect to XcodeBuildMCP?

XcodeBuildMCP is an open-source MCP server and CLI that lets Claude Code and Codex build, run and test iOS apps, drive the iOS Simulator and take screenshots. It runs on a Mac with macOS 14.5 or later and a supported Xcode installation ([requirements](https://github.com/getsentry/MobileBuildMCP), checked 26 Oct 2026). Since version 2.7.1 the package is named `mobilebuildmcp`, so current setup commands use that name. In Claude Code, run `claude mcp add MobileBuildMCP -- npx -y mobilebuildmcp@latest mcp`; in Codex, run the same line with `codex` in place of `claude`. Both start the server over stdio, next to the client on the same Mac. Only the Simulator tools are on by default; list more workflows, such as `ui-automation` for taps and swipes, in `.mobilebuildmcp/config.yaml` at the project root. Codex allows an MCP tool 60 seconds unless you set `tool_timeout_sec` inside the server's block in `~/.codex/config.toml`, and a build can take longer, so set 600.

## How do I set up XcodeBuildMCP for Claude Code?

Use the new package name. The old `xcodebuildmcp` npm package stops at 2.7.0, so a config that still says `xcodebuildmcp@latest` gets no newer releases ([npm](https://www.npmjs.com/package/xcodebuildmcp), checked 26 Oct 2026).

On a Mac with Xcode installed, one command registers the server. `npx` fetches the package when the server starts, so there is no global install ([MCP clients](https://www.mobilebuildmcp.com/docs/clients), checked 26 Oct 2026):

```bash
claude mcp add MobileBuildMCP -- npx -y mobilebuildmcp@latest mcp
```

1. Run it in your project folder. Claude Code keeps the server in local scope by default, for that project only. Add `--scope user` before the name to load it in every project, or `--scope project` to write a `.mcp.json` your team commits ([Claude Code MCP docs](https://code.claude.com/docs/en/mcp)).
2. Check the connection with `claude mcp get MobileBuildMCP`, or with `/mcp` inside a session.
3. To give the agent tap, swipe and LLDB tools, enable more workflows in a file at the project root:

   ```yaml
   # .mobilebuildmcp/config.yaml
   schemaVersion: 1
   enabledWorkflows: ["simulator", "ui-automation", "debugging"]
   ```

4. Ask for something concrete, such as "Build and run the app on an iPhone Simulator and show me any runtime errors." The agent discovers the project, lists schemes, sets session defaults and calls `build_run_sim`.

With Homebrew instead of npm, run `brew tap getsentry/xcodebuildmcp` and `brew install mobilebuildmcp`, then register `mobilebuildmcp mcp` in place of the `npx` command. The server sends its own runtime errors to Sentry by default, not your code or tool inputs; `sentryDisabled: true` in the same config file turns that off ([Privacy](https://www.mobilebuildmcp.com/docs/privacy)).

## How do I set up XcodeBuildMCP for Codex?

Codex has its own command for the same server:

```bash
codex mcp add MobileBuildMCP -- npx -y mobilebuildmcp@latest mcp
```

Or add the block to `~/.codex/config.toml` yourself, with a longer tool timeout:

```toml
[mcp_servers.MobileBuildMCP]
command = "npx"
args = ["-y", "mobilebuildmcp@latest", "mcp"]
tool_timeout_sec = 600
```

The timeout matters. Codex gives an MCP tool 60 seconds by default ([OpenAI: MCP in Codex](https://learn.chatgpt.com/docs/extend/mcp), checked 26 Oct 2026), and a build can run longer, which shows up as `timed out awaiting tools/call after 60s`. The project's docs say Codex ignores a top-level `tool_timeout_sec` for MCP tool calls, so it belongs inside the server block ([Troubleshooting](https://www.mobilebuildmcp.com/docs/troubleshooting)). A project-scoped `.codex/config.toml` also works in trusted projects, and `/mcp` in the Codex composer lists connected servers. The same `.mobilebuildmcp/config.yaml` decides which workflows Codex sees.

## What tools does XcodeBuildMCP give an agent?

The server groups its tools into workflows and advertises only the `simulator` workflow until you enable more, which keeps the tool list short in the agent's context ([Configuration](https://www.mobilebuildmcp.com/docs/configuration), checked 26 Oct 2026). Tool names below come from the project's tool manifests on the same date.

| Workflow | Example tools | What the agent can do |
| --- | --- | --- |
| `simulator` (on by default) | `list_sims`, `boot_sim`, `build_sim`, `build_run_sim`, `test_sim`, `screenshot`, `snapshot_ui` | Find the scheme, build, install and launch on a Simulator with logs captured, run tests, capture the screen and the UI hierarchy; [screenshots in pull requests](https://macswarm.com/docs/ios-simulator-screenshots-in-pull-requests/) shows where those images can go |
| `ui-automation` | `tap`, `swipe`, `type_text`, `gesture`, `wait_for_ui` | Tap and type through the app the way a tester would |
| `simulator-management` | `set_sim_location`, `set_sim_appearance`, `erase_sims` | Set a location or dark mode, reset devices |
| `debugging` | `debug_attach_sim`, `debug_breakpoint_add`, `debug_variables` | Attach LLDB, set breakpoints, read variables |
| `device` | `build_device`, `test_device`, `install_app_device` | Build and test on a connected iPhone or iPad, with code signing set up in Xcode |
| `macos`, `swift-package` | `build_run_macos`, `swift_package_test` | Mac apps and Swift packages |

The tool an agent reaches for most is `build_run_sim`: it builds the scheme, boots a Simulator if needed, installs and launches the app, and returns the path of the captured log. `session_set_defaults` stores the project, scheme and Simulator once, so later calls can leave them out ([Tools reference](https://www.mobilebuildmcp.com/docs/tools)).

## Why do some guides say XcodeBuildMCP and others MobileBuildMCP?

They are the same project. The old addresses, github.com/cameroncooke/XcodeBuildMCP and github.com/getsentry/XcodeBuildMCP, redirect to the renamed repository. The [2.7.1 changelog](https://github.com/getsentry/MobileBuildMCP/blob/main/CHANGELOG.md), published to npm on 23 September 2026, renames the npm package, the `mobilebuildmcp` binaries, the Homebrew formula, the `MOBILEBUILDMCP_*` environment variables and the `.mobilebuildmcp/config.yaml` project file. Guides written before then use the `xcodebuildmcp` names. OpenAI's [Debug in iOS simulator](https://learn.chatgpt.com/use-cases/ios-simulator-bug-debugging) use case and most MCP directories still say XcodeBuildMCP, and so does this page.

## What are the limits of running it on your own Mac?

It works well for one developer at a desk. The limits appear when you want more than that:

- **It needs that Mac.** The server drives Xcode's tools on the machine it runs on, so the Mac has to stay on and awake for as long as the agent works.
- **Parallel agents can land on one Simulator.** When no Simulator is named in the call or in session defaults, `build_run_sim` uses the first booted one ([Tools reference](https://www.mobilebuildmcp.com/docs/tools)). Give each agent its own Simulator through session defaults or named profiles.
- **Builds compete** for the same CPU and memory as your editor and everything else on the machine.
- **Hosted sessions have no Xcode.** These stdio setup commands run the MCP server alongside the client on a Mac. Installing the server in an Anthropic-hosted session, an Ubuntu VM ([Configure cloud environments](https://code.claude.com/docs/en/cloud-environments)), does not provide Xcode. This guide covers local Mac clients and agents running inside Pods; [iOS Simulator for coding agents](https://macswarm.com/ios-simulator-for-coding-agents/) covers the cloud-session question.
- **Device tools need your signing setup** and a connected iPhone or iPad ([README](https://github.com/getsentry/MobileBuildMCP)).

## How does XcodeBuildMCP work on a Macswarm Pod?

Macswarm is serverless Mac infrastructure for Claude Code and Codex. Free, Pro and Team run Pods on shared Apple silicon; Enterprise reserves Macs. A Pod is a macOS virtual machine with the Latest Xcode, iOS runtimes and three to four pre-booted Simulators, cloned fresh for one developer, and XcodeBuildMCP is preinstalled on every Pod ([Inside a Pod](https://macswarm.com/docs/inside-a-pod/)). The local commands above use upstream MobileBuildMCP. The Pod inventory documents XcodeBuildMCP as included; it does not specify a release or configuration path, so do not assume the settings above match the image.

How a session reaches a Pod depends on the agent and plan:

- **Claude Team or Enterprise:** a self-hosted environment, which Anthropic offers to Team and Enterprise plans in public beta ([Self-hosted environments](https://code.claude.com/docs/en/self-hosted-environments), checked 26 Oct 2026). The [Claude Code quickstart](https://macswarm.com/docs/quickstart-claude-code/) has the steps.
- **Claude Pro or Max:** start a Pod on Macswarm Free or Pro and sign in to Claude Code inside it. The dashboard steps are not documented yet; write to [info@macswarm.com](mailto:info@macswarm.com) and we will walk you through them.
- **Codex:** an OpenAI Agents API webhook; the [Codex quickstart](https://macswarm.com/docs/quickstart-codex/) has the steps.

Once the session runs, the agent builds with `xcodebuild` in one of the Pod's two build slots, leases a Simulator, installs and launches the app through XcodeBuildMCP, taps through it, and attaches screenshots to the pull request. What changes compared with your own Mac:

- **Each agent leases its own Simulator** for a launch or a test run, and builds queue fairly for the two slots. Two to three active agents per Pod are guaranteed; more can run and wait their turn ([Limits and queues](https://macswarm.com/docs/limits-and-queues/)).
- **You follow the agent, not a screen.** There is no SSH or screen sharing into a Pod, and it accepts no inbound connections. You watch through Claude, Codex, or the logs and screenshots in the dashboard ([Security](https://macswarm.com/docs/security/)).
- **Pod-local data is destroyed with the Pod**, ten minutes after the last session ends. Commits and rescue branches stay on your git host, and the logs and screenshots the agent produces are kept for 30 days in the region you chose ([privacy policy](https://macswarm.com/legal/privacy/#the-service)).

Billing is per second while a Pod runs, those ten idle minutes included. Free is 3 Pod-hours once, with no card; Pro is $99 a month for 300 Pod-hours and up to four Pods at a time, with a monthly spend cap you set ([pricing](https://macswarm.com/pricing/)).

### When is your own Mac the better choice?

- **One developer, one agent, a Mac already on the desk.** The setup above costs nothing beyond your Claude or OpenAI plan.
- **You test on a physical iPhone or iPad.** The `device` workflow needs a connected device and your signing setup, and a Pod comes with Simulators, not devices.
- **You want to watch the Simulator window** or step through LLDB yourself.

Without any Mac at all, [Build an iOS app without a Mac](https://macswarm.com/docs/build-ios-app-without-a-mac/) compares the other routes.

## What else do people ask?

### Is XcodeBuildMCP the same as MobileBuildMCP?

Yes. The project was renamed in version 2.7.1, published on 23 September 2026. The npm package is now `mobilebuildmcp`, the binaries are `mobilebuildmcp` and `mobilebuildmcp-doctor`, and the repository is getsentry/MobileBuildMCP; the old GitHub addresses redirect there. The `xcodebuildmcp` npm package stops at 2.7.0, so a config that still names it gets no newer releases.

### Does XcodeBuildMCP work on Linux or Windows?

No. The server requires macOS 14.5 or later and a supported Xcode installation, because it drives Xcode and the iOS Simulator, which run only on macOS. The setup commands on this page start it next to the agent on the same Mac. If you work from Linux or Windows, run the agent session on a Mac you own or rent, or on a Macswarm Pod.

### Why does Codex time out when XcodeBuildMCP builds?

Codex gives an MCP tool 60 seconds by default, and a build can take longer. Set `tool_timeout_sec = 600` inside the `[mcp_servers.MobileBuildMCP]` block of `~/.codex/config.toml`. The project's docs say Codex ignores a top-level `tool_timeout_sec` for MCP tool calls.

### Can Claude Code use XcodeBuildMCP in a cloud session?

Only when the session runs on a Mac. Installing the server in an Anthropic-hosted session, which is an Ubuntu VM, does not provide Xcode or a Simulator. A Claude Team or Enterprise organization can route cloud sessions to a Macswarm Pod through a self-hosted environment, which Anthropic offers in public beta; XcodeBuildMCP is already installed there.

### Do I need to install XcodeBuildMCP on a Macswarm Pod?

No. The Pod inventory lists XcodeBuildMCP next to the Latest Xcode, iOS runtimes and pre-booted Simulators. It does not specify which release or configuration path the image uses, so if your setup depends on one, or your project needs another tool in the base image, write to [info@macswarm.com](mailto:info@macswarm.com).