Content
<img src="banner.png" alt="XcodeBuild MCP" width="600"/>
A Model Context Protocol (MCP) server and CLI that provides tools for agent use when working on iOS and macOS projects.
[](https://github.com/cameroncooke/XcodeBuildMCP/actions/workflows/ci.yml)
[](https://badge.fury.io/js/xcodebuildmcp) [](https://opensource.org/licenses/MIT) [](https://nodejs.org/) [](https://developer.apple.com/xcode/) [](https://www.apple.com/macos/) [](https://modelcontextprotocol.io/) [](https://deepwiki.com/cameroncooke/XcodeBuildMCP)
## Installation
### CLI Installation
```bash
npm install -g xcodebuildmcp@beta
xcodebuildmcp --help
```
### MCP Server Installation
Add XcodeBuildMCP to your MCP client configuration. Most clients use JSON configuration with the following server entry:
```json
"XcodeBuildMCP": {
"command": "npx",
"args": ["-y", "xcodebuildmcp@beta", "mcp"]
}
```
<details>
<summary>Cursor</summary>
<br />
Add to `~/.cursor/mcp.json`:
```json
{
"mcpServers": {
"XcodeBuildMCP": {
"command": "npx",
"args": ["-y", "xcodebuildmcp@beta", "mcp"]
}
}
}
```
Or use the quick install link:
[](https://cursor.com/en-US/install-mcp?name=XcodeBuildMCP&config=eyJjb21tYW5kIjoibnB4IC15IHhjb2RlYnVpbGRtY3BAYmV0YSBtY3AifQ%3D%3D)
<br />
</details>
<details>
<summary>Claude Code</summary>
<br />
Run:
```bash
claude mcp add XcodeBuildMCP -- npx -y xcodebuildmcp@beta mcp
```
<br />
</details>
<details>
<summary>Codex CLI</summary>
<br />
Run:
```bash
codex mcp add XcodeBuildMCP -- npx -y xcodebuildmcp@beta mcp
```
Or add to `~/.codex/config.toml`:
```toml
[mcp_servers.XcodeBuildMCP]
command = "npx"
args = ["-y", "xcodebuildmcp@beta", "mcp"]
```
<br />
</details>
<details>
<summary>Claude Desktop</summary>
<br />
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"XcodeBuildMCP": {
"command": "npx",
"args": ["-y", "xcodebuildmcp@beta", "mcp"]
}
}
}
```
<br />
</details>
<details>
<summary>VS Code / VS Code Insiders</summary>
<br />
Add to your VS Code settings JSON:
```json
"mcp": {
"servers": {
"XcodeBuildMCP": {
"command": "npx",
"args": ["-y", "xcodebuildmcp@beta", "mcp"]
}
}
}
```
Or use the quick install links:
[](https://cursor.com/en-US/install-mcp?name=XcodeBuildMCP&config=eyJjb21tYW5kIjoibnB4IC15IHhjb2RlYnVpbGRtY3BAYmV0YSBtY3AifQ%3D%3D)
[](vscode-insiders:mcp/install?%7B%22name%22%3A%22XcodeBuildMCP%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22xcodebuildmcp%40beta%22%2C%22mcp%22%5D%7D)
<br />
</details>
<details>
<summary>Windsurf</summary>
<br />
Add to `~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"XcodeBuildMCP": {
"command": "npx",
"args": ["-y", "xcodebuildmcp@beta", "mcp"]
}
}
}
```
<br />
</details>
<details>
<summary>Trae</summary>
<br />
Add to `~/Library/Application Support/Trae/User/mcp.json`:
```json
{
"mcpServers": {
"XcodeBuildMCP": {
"command": "npx",
"args": ["-y", "xcodebuildmcp@beta", "mcp"]
}
}
}
```
<br />
</details>
<br />
For other installation options see [Getting Started](docs/GETTING_STARTED.md)
When configuring a client manually, ensure the command includes the `mcp` subcommand (for example, `npx -y xcodebuildmcp@latest mcp`).
## Requirements
- macOS 14.5 or later
- Xcode 16.x or later
- Node.js 18.x or later
## 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, copy and paste the command below into a terminal and follow the on-screen instructions.
```bash
curl -fsSL https://raw.githubusercontent.com/cameroncooke/XcodeBuildMCP/main/scripts/install-skill.sh -o install-skill.sh && bash install-skill.sh
```
For further information on how to install the skill, see: [docs/SKILLS.md](docs/SKILLS.md)
## 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 [docs/DEVICE_CODE_SIGNING.md](docs/DEVICE_CODE_SIGNING.md).
## Privacy
XcodeBuildMCP uses Sentry for error telemetry. For more information or to opt out of error telemetry see [docs/PRIVACY.md](docs/PRIVACY.md).
## 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:
```bash
# Install globally
npm install -g xcodebuildmcp@beta
# Start the MCP server (for MCP clients)
xcodebuildmcp mcp
# List available tools
xcodebuildmcp tools
# Build for simulator
xcodebuildmcp simulator build-sim --scheme MyApp --project-path ./MyApp.xcodeproj
```
The CLI uses a per-workspace daemon for stateful operations (log capture, debugging, etc.) that auto-starts when needed. See [docs/CLI.md](docs/CLI.md) for full documentation.
## Documentation
- Getting started: [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md)
- CLI usage: [docs/CLI.md](docs/CLI.md)
- Configuration and options: [docs/CONFIGURATION.md](docs/CONFIGURATION.md)
- Tools reference: [docs/TOOLS.md](docs/TOOLS.md)
- Troubleshooting: [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)
- Privacy: [docs/PRIVACY.md](docs/PRIVACY.md)
- Skills: [docs/SKILLS.md](docs/SKILLS.md)
- Contributing: [docs/dev/CONTRIBUTING.md](docs/dev/CONTRIBUTING.md)
## Licence
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
