A Model Context Protocol (MCP) server that provides Xcode-related tools for integration with AI assistants and other MCP clients.
This project implements an MCP server that exposes Xcode operations as tools that can be invoked by AI agents via the MCP protocol. It enables programmatic interaction with Xcode projects through a standardised interface, optimised for agent-driven development workflows.
The XcodeBuild MCP tool exists primarily to streamline and standardise interaction between AI agents and Xcode projects. By providing dedicated tools for common Xcode operations, it removes reliance on manual or potentially incorrect command-line invocations.
This ensures a reliable and efficient development process, allowing agents to seamlessly leverage Xcode's capabilities while reducing the risk of configuration errors.
Critically, this MCP enables AI agents to independently validate code changes by building projects, inspecting errors, and iterating autonomously. In contrast to user-driven tools like Sweetpad, XcodeBuild MCP empowers agents to automate these workflows effectively.
The XcodeBuildMCP server provides the following tool capabilities:
- Discover Projects: Xcode projects and workspaces discovery
- Build Operations: Platform-specific build tools for macOS, iOS simulator, and iOS device targets
- Project Information: Tools to list schemes and show build settings for Xcode projects and workspaces
- Clean Operations: Clean build products using xcodebuild's native clean action
- Simulator Control: List, boot, and open iOS simulators
- App Deployment: Install and launch apps on iOS simulators
- Log Capture: Capture run-time logs from a simulator
- UI Automation: Interact with simulator UI elements (beta)
- Screenshot: Capture screenshots from a simulator (beta)
- Bundle ID Extraction: Extract bundle identifiers from iOS and macOS app bundles
- App Launching: Launch built applications on both simulators and macOS
- macOS 14.5 or later
- Xcode 18.x or later
- mise
To install mise:
# macOS (Homebrew)
brew install mise
# Other installation methods
# See https://mise.jdx.dev/getting-started.htmlFor more information about mise, visit the official documentation.
Configure your MCP client (Windsurf, Cursor, Claude Desktop, etc.) to use the XcodeBuildMCP server by adding the following configuration, changing the version number to match the version you wish to use:
{
"mcpServers": {
"XcodeBuildMCP": {
"command": "mise",
"args": [
"x",
"npm:[email protected]",
"--",
"xcodebuildmcp"
]
}
}
}Note
When using mise avoid using the @latest tag as mise will cache the package and may not update to the latest version automatically, instead prefer an explicit version number.
Important
Please note that XcodeBuildMCP will request xcodebuild to skip macro validation. This is to avoid errors when building projects that use Swift Macros.
For UI automation features (tap, swipe, screenshot, etc.), you'll need to install Facebook's idb_companion:
brew tap facebook/fb
brew install idb-companionThe idb client is also required but XcodeBuildMCP attmepts to install it for you. If you find that the UI automation features are still not available you can install the client manually using the following command (assumes you have Python installed):
pip install fb-idb==1.1.7Important
Please note that UI automation features are currently in beta so there might be some rough edges. If you encounter any issues, please report them in the issue tracker.
Note
Displaying images in tool responses and embedding them in chat context may not be supported by all MCP Clients; it's currently known to be supported in Cursor.
If you encounter issues with XcodeBuildMCP, the diagnostic tool can help identify the problem by providing detailed information about your environment and dependencies.
The diagnostic tool is a standalone utility that checks your system configuration and reports on the status of all dependencies required by XcodeBuildMCP. It's particularly useful when reporting issues.
# Run the diagnostic tool using mise
mise x npm:[email protected] -- xcodebuildmcp-diagnostic# Run the diagnostic tool using npx
npx [email protected] xcodebuildmcp-diagnosticThe diagnostic tool will output comprehensive information about:
- System and Node.js environment
- Xcode installation and configuration
- Required dependencies (xcodebuild, idb, etc.)
- Environment variables affecting XcodeBuildMCP
- Feature availability status
When reporting issues on GitHub, please include the full output from the diagnostic tool to help with troubleshooting.
This project uses Sentry for error monitoring and diagnostics. Sentry helps us track issues, crashes, and unexpected errors to improve the reliability and stability of XcodeBuildMCP.
- Only error-level logs and diagnostic information are sent to Sentry by default.
- Error logs may include details such as error messages, stack traces, and (in some cases) file paths or project names. You can review the sources in this repository to see exactly what is logged.
- If you do not wish to send error logs to Sentry, you can opt out by setting the environment variable
SENTRY_DISABLED=true.
Example MCP client configuration:
{
"mcpServers": {
"XcodeBuildMCP": {
"command": "mise",
"args": [
"x",
"npm:[email protected]",
"--",
"xcodebuildmcp"
],
"env": {
"SENTRY_DISABLED": "true"
}
}
}
}
Demo3.mp4
Contributions are welcome! Here's how you can help improve XcodeBuildMCP.
See our CONTRIBUTING document for more information on how to configure your local environment and contribute to the project.
This project is licensed under the MIT License - see the LICENSE file for details.