XcodeBuildMCP README

A Model Context Protocol (MCP) server and CLI that provides tools for agent use when working on iOS and macOS projects.

Installation

MobileBuildMCP ships as a single package with two modes: a CLI for direct terminal use and an MCP server for AI coding agents. Either install method gives you both.

Option A — Homebrew

brew tap getsentry/xcodebuildmcp
brew install mobilebuildmcp

Option B — npm (Node.js 18+)

npm install -g mobilebuildmcp@latest

Verify either install:

mobilebuildmcp --help

Connect your MCP client

Drop-in config snippets for Cursor, Claude Code, Codex, can be found in the official docs page MCP Clients. Most clients can also run the MCP server on demand via npx -y mobilebuildmcp@latest mcp without a global install.

Requirements

• macOS 14.5 or later
• Xcode 16.x or later
• Node.js 18.x or later (not required for Homebrew installation)

Skills

MobileBuildMCP now includes two optional agent skills:

• MCP Skill: Primes the agent with instructions on how to use the MCP server's tools (optional when using the MCP server).

• CLI Skill: Primes the agent with instructions on how to navigate the CLI (recommended when using the CLI).

To install with a global binary:

mobilebuildmcp init

Or install directly via npx without a global install:

npx -y mobilebuildmcp@latest init

For further information on installing skills, see Agent Skills.

Notes

• MobileBuildMCP requests xcodebuild to skip macro validation to avoid errors when building projects that use Swift Macros.
• Device tools require code signing to be configured in Xcode. See Device Code Signing.

Privacy

MobileBuildMCP uses Sentry for internal runtime error telemetry only. For details and opt-out instructions, see Privacy & Telemetry.

CLI

MobileBuildMCP provides a unified command-line interface. The mcp subcommand starts the MCP server, while all other commands provide direct terminal access to tools:

# Install globally
npm install -g mobilebuildmcp@latest

# Start the MCP server (for MCP clients)
mobilebuildmcp mcp

# List available tools
mobilebuildmcp tools

# Build for simulator
mobilebuildmcp simulator build --scheme MyApp --project-path ./MyApp.xcodeproj

# Prepare portable test products without running tests
mobilebuildmcp simulator build --scheme MyApp --project-path ./MyApp.xcodeproj --simulator-name "iPhone 17" --build-for-testing --test-products-path ./MyApp.xctestproducts

# Run previously prepared test products
mobilebuildmcp simulator test --test-products-path ./MyApp.xctestproducts --simulator-name "iPhone 17"

Check for updates and upgrade in place:

mobilebuildmcp upgrade --check
mobilebuildmcp upgrade --yes

The CLI uses a per-workspace daemon for stateful operations (log capture, debugging, etc.) that auto-starts when needed. See the CLI guide for full documentation.

Documentation

• Installation: https://github.com/getsentry/xcodebuildmcp.com/blob/main/app/docs/_content/installation.mdx
• Setup: https://github.com/getsentry/xcodebuildmcp.com/blob/main/app/docs/_content/setup.mdx
• MCP clients: https://github.com/getsentry/xcodebuildmcp.com/blob/main/app/docs/_content/clients.mdx
• CLI usage: https://github.com/getsentry/xcodebuildmcp.com/blob/main/app/docs/_content/cli.mdx
• Configuration and options: https://github.com/getsentry/xcodebuildmcp.com/blob/main/app/docs/_content/configuration.mdx
• Tools reference: https://github.com/getsentry/xcodebuildmcp.com/blob/main/app/docs/_content/tools.mdx
• Troubleshooting: https://github.com/getsentry/xcodebuildmcp.com/blob/main/app/docs/_content/troubleshooting.mdx
• Privacy: https://github.com/getsentry/xcodebuildmcp.com/blob/main/app/docs/_content/privacy.mdx
• Skills: https://github.com/getsentry/xcodebuildmcp.com/blob/main/app/docs/_content/skills.mdx
• Contributing: https://github.com/getsentry/xcodebuildmcp.com/blob/main/app/docs/_content/contributing.mdx

Licence

This project is licensed under the MIT License - see the LICENSE file for details. For third-party licensing notices see the THIRD_PARTY_LICENSES file for details. For npm package attributions see the THIRD_PARTY_PACKAGE_LICENSES file for details.