A Model Context Protocol (MCP) server and CLI that provides tools for agent use when working on iOS and macOS projects.
Requirements
- macOS 14.5 or later
- Xcode 16.x or later
- Node.js 18.x or later (not required for Homebrew installation)
Skills
XcodeBuildMCP 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:
xcodebuildmcp init
Or install directly via npx without a global install:
npx -y xcodebuildmcp@latest init
For further information on installing skills, see Agent Skills.
Notes
- XcodeBuildMCP 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
XcodeBuildMCP uses Sentry for internal runtime error telemetry only. For details and opt-out instructions, see Privacy & Telemetry.
CLI
XcodeBuildMCP 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 xcodebuildmcp@latest
# Start the MCP server (for MCP clients)
xcodebuildmcp mcp
# List available tools
xcodebuildmcp tools
# Build for simulator
xcodebuildmcp simulator build --scheme MyApp --project-path ./MyApp.xcodeproj
# Prepare portable test products without running tests
xcodebuildmcp 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
xcodebuildmcp simulator test --test-products-path ./MyApp.xctestproducts --simulator-name "iPhone 17"
Check for updates and upgrade in place:
xcodebuildmcp upgrade --check
xcodebuildmcp 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
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.