Skip to content

Latest commit

 

History

History
155 lines (117 loc) · 3.7 KB

GETTING_STARTED.md

File metadata and controls

155 lines (117 loc) · 3.7 KB

Getting Started

Prerequisites

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

Choose Your Interface

XcodeBuildMCP provides a unified CLI with two modes:

Command Use Case
xcodebuildmcp mcp Start MCP server for AI-assisted development
xcodebuildmcp <workflow> <tool> Direct terminal usage, scripts, CI pipelines

Both share the same tools and configuration.

Installation

Both methods give you the CLI and the MCP server.

Option A — Homebrew (no Node.js required)

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.

Option B — npm / npx (Node.js 18+)

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"]
}

Using @latest ensures clients resolve the newest version on each run.

See CLI.md for full CLI documentation.

Project config (optional)

For deterministic session defaults and runtime configuration, add a config file at:

<workspace-root>/.xcodebuildmcp/config.yaml

Use the setup wizard to create or update this file interactively:

xcodebuildmcp setup

See CONFIGURATION.md for the full schema and examples.

Client-specific configuration

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

Cursor

Recommended (project-scoped): create .cursor/mcp.json in your project root:

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

If you use a global Cursor config at ~/.cursor/mcp.json, use this variant to align startup with the active workspace:

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

OpenAI Codex CLI

Codex uses TOML for MCP configuration. Add this to ~/.codex/config.toml:

[mcp_servers.XcodeBuildMCP]
command = "npx"
args = ["-y", "xcodebuildmcp@latest", "mcp"]
env = { "XCODEBUILDMCP_SENTRY_DISABLED" = "false" }

If you see tool calls timing out (for example, timed out awaiting tools/call after 60s), increase the timeout:

tool_timeout_sec = 600

For more info see the OpenAI Codex configuration docs: https://github.com/openai/codex/blob/main/docs/config.md#connecting-to-mcp-servers

Claude Code CLI

# Add XcodeBuildMCP server to Claude Code
claude mcp add XcodeBuildMCP -- npx -y xcodebuildmcp@latest mcp

# Or with environment variables
claude mcp add XcodeBuildMCP -e XCODEBUILDMCP_SENTRY_DISABLED=false -- npx -y xcodebuildmcp@latest mcp

Note: XcodeBuildMCP requests xcodebuild to skip macro validation to avoid Swift Macro build errors.

AdaL CLI

Run the following command inside the AdaL CLI prompt:

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

Next steps