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

XcodeBuildMCP ships as a single package with two modes: a CLI for direct terminal use and an MCP server for AI coding agents. Both installation methods give you both modes.

brew tap getsentry/xcodebuildmcp
brew install xcodebuildmcp

Use the CLI:

xcodebuildmcp --help

MCP client config:

"XcodeBuildMCP": {
  "command": "xcodebuildmcp",
  "args": ["mcp"]
}

Upgrade later with brew update && brew upgrade xcodebuildmcp.

For CLI use, install globally:

npm install -g xcodebuildmcp@latest
xcodebuildmcp --help

For MCP server only, no global install needed — add directly to your client config:

"XcodeBuildMCP": {
  "command": "npx",
  "args": ["-y", "xcodebuildmcp@latest", "mcp"]
}

To pin a specific version, replace @latest with an exact version (e.g. xcodebuildmcp@latest).

The examples below use npx (Option B). If you installed via Homebrew, replace the command with "command": "xcodebuildmcp", "args": ["mcp"] instead.

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "npx",
      "args": ["-y", "xcodebuildmcp@latest", "mcp"]
    }
  }
}

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "/bin/zsh",
      "args": [
        "-lc",
        "cd \"${workspaceFolder}\" && exec npx -y xcodebuildmcp@latest mcp"
      ]
    }
  }
}

claude mcp add XcodeBuildMCP -- npx -y xcodebuildmcp@latest mcp

codex mcp add XcodeBuildMCP -- npx -y xcodebuildmcp@latest mcp

[mcp_servers.XcodeBuildMCP]
command = "npx"
args = ["-y", "xcodebuildmcp@latest", "mcp"]

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "npx",
      "args": ["-y", "xcodebuildmcp@latest", "mcp"]
    }
  }
}

"mcp": {
  "servers": {
    "XcodeBuildMCP": {
      "command": "npx",
      "args": ["-y", "xcodebuildmcp@latest", "mcp"]
    }
  }
}

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "npx",
      "args": ["-y", "xcodebuildmcp@latest", "mcp"]
    }
  }
}

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "npx",
      "args": ["-y", "xcodebuildmcp@latest", "mcp"]
    }
  }
}

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "npx",
      "args": ["-y", "xcodebuildmcp@latest", "mcp"]
    }
  }
}

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "npx",
      "args": ["-y", "xcodebuildmcp@latest", "mcp"]
    }
  }
}

[mcp_servers.XcodeBuildMCP]
args = [
"-lc",
"PATH=/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin; export NVM_DIR=\"$HOME/.nvm\"; [ -s \"$NVM_DIR/nvm.sh\" ] && . \"$NVM_DIR/nvm.sh\"; nvm use --silent >/dev/null 2>&1 || true; npx -y xcodebuildmcp@latest mcp"
]
command = "/bin/zsh"
enabled = true
tool_timeout_sec = 10000

  // ... rest of file ...
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "/bin/zsh",
      "args": [
        "-lc",
        "PATH=/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin; export NVM_DIR=\"$HOME/.nvm\"; [ -s \"$NVM_DIR/nvm.sh\" ] && . \"$NVM_DIR/nvm.sh\"; nvm use --silent >/dev/null 2>&1 || true; npx -y xcodebuildmcp@latest mcp"
      ]
    }
  }
}

/mcp add XcodeBuildMCP --command npx --args "-y,xcodebuildmcp@latest,mcp"

For other installation options see Getting Started.

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

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: docs/SKILLS.md

• 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.

XcodeBuildMCP uses Sentry for internal runtime error telemetry only. For details and opt-out instructions, see docs/PRIVACY.md.

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

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 docs/CLI.md for full documentation.

• Getting started: docs/GETTING_STARTED.md
• CLI usage: docs/CLI.md
• Configuration and options: docs/CONFIGURATION.md
• Tools reference: docs/TOOLS.md
• Troubleshooting: docs/TROUBLESHOOTING.md
• Privacy: docs/PRIVACY.md
• Skills: docs/SKILLS.md
• Contributing: docs/dev/CONTRIBUTING.md

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.