XcodeBuildMCP
by getsentry
README.md
A Model Context Protocol (MCP) server and CLI that provides tools for agent use when working on iOS and macOS projects.
[](https://github.com/getsentry/MobileBuildMCP/actions/workflows/ci.yml)
[](https://badge.fury.io/js/mobilebuildmcp) [](https://opensource.org/licenses/MIT) [](https://nodejs.org/) [](https://developer.apple.com/xcode/) [](https://www.apple.com/macos/) [](https://modelcontextprotocol.io/) [](https://deepwiki.com/getsentry/MobileBuildMCP) [](https://www.agentaudit.dev/skills/xcodebuildmcp) [](https://pkg.pr.new/~/getsentry/MobileBuildMCP)
## 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
```bash
brew tap getsentry/xcodebuildmcp
brew install mobilebuildmcp
```
### Option B — npm (Node.js 18+)
```bash
npm install -g mobilebuildmcp@latest
```
Verify either install:
```bash
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](https://github.com/getsentry/xcodebuildmcp.com/blob/main/app/docs/_content/clients.mdx). 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:
```bash
mobilebuildmcp init
```
Or install directly via npx without a global install:
```bash
npx -y mobilebuildmcp@latest init
```
For further information on installing skills, see [Agent Skills](https://github.com/getsentry/xcodebuildmcp.com/blob/main/app/docs/_content/skills.mdx).
## 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](https://github.com/getsentry/xcodebuildmcp.com/blob/main/app/docs/_content/device-signing.mdx).
## Privacy
MobileBuildMCP uses Sentry for internal runtime error telemetry only. For details and opt-out instructions, see [Privacy & Telemetry](https://github.com/getsentry/xcodebuildmcp.com/blob/main/app/docs/_content/privacy.mdx).
## 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:
```bash
# 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:
```bash
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](https://github.com/getsentry/xcodebuildmcp.com/blob/main/app/docs/_content/cli.mdx) for full documentation.
## Documentation
- Installation: [https://github.com/getsentry/xcodebuildmcp.com/blob/main/app/docs/_content/installation.mdx](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](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](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](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](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](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](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](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](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](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](LICENSE) file for details.
For third-party licensing notices see the [THIRD_PARTY_LICENSES](THIRD_PARTY_LICENSES) file for details.
For npm package attributions see the [THIRD_PARTY_PACKAGE_LICENSES](THIRD_PARTY_PACKAGE_LICENSES.md) file for details.
TDQS
B3.2/5.0
Scored across 83 tools
Disambiguation2/5
The tool set has significant overlap and ambiguity, particularly in build and test operations where multiple tools differ only by target (project vs. workspace) or identifier type (UUID vs. name). For example, there are 4 variants each for building, getting app paths, and testing on simulators, making it easy for an agent to misselect. While descriptions clarify parameters, the sheer number of similar tools creates confusion.
Naming Consistency4/5
Tool names follow a consistent snake_case pattern with a clear verb_noun structure (e.g., build_dev_proj, list_sims, describe_ui). However, there are minor deviations like 'button' (noun only) and 'doctor' (no verb), and some names are overly verbose due to parameter distinctions (e.g., build_run_sim_name_ws). Overall, the naming is predictable but not perfectly uniform.
Tool Count2/5
With 83 tools, the count is excessive for the Xcode build and testing domain. Many tools are redundant variations (e.g., separate tools for project vs. workspace, UUID vs. name), leading to bloat. A more streamlined set with parameterized options would be more appropriate, as the current size overwhelms and complicates agent decision-making.
Completeness5/5
The tool set comprehensively covers Xcode development workflows, including building, testing, simulator management, UI automation, logging, and Swift package operations. It supports CRUD-like actions (e.g., create projects via scaffold, run/stop apps) across multiple platforms (iOS, macOS) with no obvious gaps, enabling end-to-end automation without dead ends.
Maintenance
ActivityActive
ResponsivenessWithin a week