XcodeBuildMCP setup: installing and configuring MobileBuildMCP

Short answer: XcodeBuildMCP has been renamed MobileBuildMCP. The repository is getsentry/MobileBuildMCP (the old XcodeBuildMCP GitHub URL redirects there), the npm package and CLI are mobilebuildmcp, and the docs live at mobilebuildmcp.com. The Homebrew tap still carries the old name: getsentry/xcodebuildmcp. Many tutorials that rank for "XcodeBuildMCP" still show xcodebuildmcp commands; this page uses the current ones. The docs site showed v2.7.1 on 2026-10-16; the repo had 6,485 GitHub stars and an MIT license.

What it does

MobileBuildMCP is one package with two modes: an MCP server for coding agents and a CLI for your terminal or CI. Tools are grouped into workflows (CLI docs):

Requirements

From the installation docs: macOS 14.5 or later, Xcode 16 or later (Xcode 26+ unlocks the Xcode IDE Bridge), Node.js 18+ for the npm path, or Homebrew.

Step 1: Install

Homebrew (recommended by the docs, no Node.js needed):

brew tap getsentry/xcodebuildmcp
brew install mobilebuildmcp

npm:

npm install -g mobilebuildmcp@latest
mobilebuildmcp --help

If you only use it as an MCP server, you can skip the global install and let your client run npx -y mobilebuildmcp@latest mcp. Check your environment with:

npx --package mobilebuildmcp@latest mobilebuildmcp-doctor

Step 2: Connect your agent

All snippets come from the official MCP Clients page. If you installed with Homebrew, the docs say to use "command": "mobilebuildmcp" with "args": ["mcp"] instead of npx.

Claude Code

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

Cursor (project-scoped .cursor/mcp.json, recommended by the docs)

{
  "mcpServers": {
    "MobileBuildMCP": {
      "command": "npx",
      "args": ["-y", "mobilebuildmcp@latest", "mcp"]
    }
  }
}

For the global ~/.cursor/mcp.json, the docs add "env": { "MOBILEBUILDMCP_CWD": "${workspaceFolder}" } so the server starts in the active workspace.

Codex CLI (~/.codex/config.toml)

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

The docs add tool_timeout_sec when you hit "timed out awaiting tools/call after 60s"; Codex ignores a top-level tool_timeout_sec.

Windsurf (~/.codeium/windsurf/mcp_config.json) and Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json) use the same mcpServers block as Cursor.

Xcode's own agents (Xcode 26.3+): the docs provide a /bin/zsh -lc wrapper because the in-Xcode agents start with a minimal PATH and often cannot find npx. For Claude Code inside Xcode the file is ~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/.claude.json; for Codex inside Xcode it is a project-scoped .codex/config.toml. Copy the exact block from the clients page.

Step 3: Run the setup wizard

In your project root:

mobilebuildmcp setup

The wizard (setup docs) creates .mobilebuildmcp/config.yaml and asks for target platforms, which workflows to enable, project/workspace path, scheme, configuration and a default simulator. It pre-selects only conservative defaults (simulator, plus macos if you build for macOS); device, debugging, ui-automation and swift-package are opt-in. If your client does not read the config file from the workspace, mobilebuildmcp setup --format mcp-json exports an env-based block to paste into the client config.

A minimal config from the configuration docs:

schemaVersion: 1
enabledWorkflows: ["simulator", "ui-automation", "debugging"]

Settings are layered (highest wins): the agent's session_set_defaults call during a session, then .mobilebuildmcp/config.yaml, then environment variables. Commit the config file so your team shares it.

Step 4 (optional): Install the agent skill

mobilebuildmcp init

Per the docs, this detects your client and installs a skill (CLI or MCP variant) so the agent uses the tools without rediscovering conventions each session.

Step 5: First build

Ask your agent something like: "Build and run my app on an iPhone 17 simulator and show me any runtime errors." The setup docs show the expected sequence: discover_projs, list_schemes, session_set_defaults, then build_run_sim. After the first session_set_defaults, later calls reuse the project, scheme and simulator.

Troubleshooting

MobileBuildMCP vs Apple's xcrun mcpbridge

Xcode 26.3+ ships its own MCP server that talks to the running IDE (builds, tests, SwiftUI preview rendering, doc search). MobileBuildMCP drives the toolchain without Xcode open, adds devices, LLDB and UI automation, and its docs describe an opt-in xcode-ide workflow that bridges to Xcode's tools. Comparison: Best MCP servers for Xcode. Catalog entries: MobileBuildMCP, Xcode external agents.

Add these next

• iOS Simulator MCP for accessibility-tree UI checks.

• Xcode Build Optimization skill to speed up the builds the agent triggers.

• SwiftUI Pro so the code it builds follows current SwiftUI.