XcodeMCP

What is XcodeMCP?

XcodeMCP is a Model Context Protocol (MCP) server and standalone CLI that controls Xcode directly through JavaScript for Automation (JXA). It provides tools for building, running, testing, debugging, parsing build logs, analyzing XCResult files, and validating the environment. It can run alongside Apple’s official Xcode MCP server in sidekick mode to offer complementary tools.

How to use XcodeMCP?

Install via npx -y xcodemcp@latest or globally with npm install -g xcodemcp. Use it as an MCP server by adding a JSON configuration to MCP clients (Claude Desktop, VS Code, etc.) or as a CLI tool with the xcodecontrol command. For side-by-side use with Apple’s official Xcode MCP, start with --sidekick-only to exclude build/run/test/debug tools. Optional but recommended: install XCLogParser via brew install xclogparser. Requirements: macOS with Xcode and Node.js 18+.

Key features of XcodeMCP

• Controls Xcode directly through JXA (not xcodebuild CLI)
• XCResult analysis with screenshot extraction and UI hierarchy
• Build log parsing with XCLogParser for precise error locations
• Comprehensive health checks and environment validation
• Sidekick mode to complement Apple’s official Xcode MCP
• Full‑featured CLI with 100% MCP server feature parity

Use cases of XcodeMCP

• Build and run Xcode projects from an AI coding assistant
• Run tests, browse results, and extract debug attachments
• Manage project schemes and workspaces programmatically
• Debug sessions and stop current operations
• Analyze test failures with console logs and UI hierarchy snapshots

FAQ from XcodeMCP

What is sidekick mode?

Sidekick mode (--sidekick-only) includes only project management and XCResult analysis tools, excluding build/run/test/debug operations. It is designed to work alongside Apple’s official Xcode MCP server without duplicating functionality.

How can I use XcodeMCP alongside Apple’s official Xcode MCP?

Enable Xcode Tools in Xcode settings, then add Apple’s MCP with xcrun mcpbridge and XcodeMCP with --sidekick-only to your MCP configuration. The README provides JSON and Claude Code CLI examples for both servers.

Can I set preferred values to avoid repetitive parameters?

Yes. Use environment variables XCODE_MCP_PREFERRED_SCHEME and XCODE_MCP_PREFERRED_XCODEPROJ to make tool parameters optional, defaulting to those values. They can still be overridden explicitly.

What are the system requirements?

macOS with Xcode installed, Node.js 18 or later, and optionally XCLogParser (recommended for build log parsing). No other runtime dependencies are required.

How do I troubleshoot if the MCP fails in Claude Code?

Run npx -y xcodemcp@latest manually from the project folder to see any error output. Common issues include missing Node.js, Xcode, or permission problems.