XcodeBuildMCP setup for Claude Code and Codex

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, 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, 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, checked 26 Oct 2026):

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

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).
Check the connection with claude mcp get MobileBuildMCP, or with /mcp inside a session.

To give the agent tap, swipe and LLDB tools, enable more workflows in a file at the project root:

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

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).

How do I set up XcodeBuildMCP for Codex?

Codex has its own command for the same server:

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

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

[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, 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). 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, checked 26 Oct 2026). Tool names below come from the project’s tool manifests on the same date.

What tools does XcodeBuildMCP give an agent?
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 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).

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, 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 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). 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), does not provide Xcode. This guide covers local Mac clients and agents running inside Pods; iOS Simulator for coding agents covers the cloud-session question.
Device tools need your signing setup and a connected iPhone or iPad (README).

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). 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, checked 26 Oct 2026). The Claude Code quickstart 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 and we will walk you through them.
Codex: an OpenAI Agents API webhook; the Codex quickstart 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).
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).
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).

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).

Start free with 3 Pod-hours, no card

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 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.

Reviewed October 26, 2026. Facts on this page are rechecked when the product changes.