Xcodemcp

Using with Apple's Official Xcode MCP: Apple now provides an official Xcode MCP server. XcodeMCP can run alongside it in sidekick mode (--sidekick-only), providing complementary tools like project management and XCResult analysis. In a future version, XcodeMCP will transition to sidekick-only mode by default. See configuration below.

XcodeMCP

Model Context Protocol (MCP) server that controls Xcode directly through JavaScript for Automation (JXA). Available as both an MCP server and a standalone CLI.

What it does

• Controls Xcode directly through JavaScript for Automation (not xcodebuild CLI)
• Opens projects, builds, runs, tests, and debugs from within Xcode
• Parses build logs with precise error locations using XCLogParser
• Provides comprehensive environment validation and health checks
• Supports graceful degradation when optional dependencies are missing
• NEW: Includes a full-featured CLI with 100% MCP server feature parity

Requirements

• macOS with Xcode installed
• Node.js 18+
• XCLogParser (recommended): brew install xclogparser

Usage

XcodeMCP can be used in two ways:

1. MCP Server: Integrate with Claude Desktop, VS Code, or other MCP clients
2. CLI Tool: Run commands directly from the terminal with xcodecontrol

Quick Install

XCLogParser is recommended but optional:

brew install xclogparser

Install from npm

Run directly with npx:

npx -y xcodemcp@latest

Or install globally:

npm install -g xcodemcp

MCP Configuration

Add to your MCP configuration:

{

"mcpServers": { "xcodemcp": { "command": "npx", "args": ["-y", "xcodemcp@latest"], "env": { } } } }

Claude Code CLI Setup

To add XcodeMCP to Claude Code using the command line:

claude mcp add-json XcodeMCP '{

"command": "npx", "args": ["-y", "xcodemcp@latest"], "env": { } }'

Without the clean build folder tool

To add XcodeMCP to Claude Code using the command line:

claude mcp add-json XcodeMCP '{

"command": "npx", "args": ["-y", "xcodemcp@latest", "--no-clean"], "env": { } }'

Using Preferred Values for Single Project Workflows

For projects where you're working with a single xcodeproj and scheme, you can configure preferred values to make tool parameters optional:

claude mcp add-json XcodeMCP '{

"command": "npx", "args": ["-y", "xcodemcp@latest"], "env": { "XCODE_MCP_PREFERRED_SCHEME": "MyApp", "XCODE_MCP_PREFERRED_XCODEPROJ": "MyApp.xcodeproj" } }'

With preferred values configured:

• Tool parameters become optional instead of required
• Tool descriptions show default values (e.g., "defaults to MyApp.xcodeproj")
• You can still override defaults by providing explicit parameters
• Reduces repetition when working with a single project

Troubleshooting

If /mcp in Claude Code indicates the MCP failed, try running it from the project folder manually to see what the output is: npx -y xcodemcp@latest

Sidekick Mode

When using XcodeMCP alongside Apple's official Xcode MCP server, enable sidekick mode to only include complementary tools:

• Project management: Open/close projects, manage schemes, workspace info
• XCResult analysis: Browse test results, extract screenshots, inspect UI hierarchies

This excludes build/run/test/debug tools that Apple's MCP handles natively.

Claude Code CLI Setup (Both Servers)

First, enable Xcode Tools in Xcode > Settings > Intelligence > Model Context Protocol.

Then add both Apple's Xcode MCP and XcodeMCP in sidekick mode:

# Add Apple's official Xcode MCP

claude mcp add --transport stdio xcode -- xcrun mcpbridge

Add XcodeMCP in sidekick mode (project management + XCResult analysis)

claude mcp add-json xcodemcp '{"command": "npx", "args": ["-y", "xcodemcp@latest", "--sidekick-only"]}'

JSON Configuration (Both Servers)

{

"mcpServers": { "xcode": { "command": "xcrun", "args": ["mcpbridge"] }, "xcodemcp": { "command": "npx", "args": ["-y", "xcodemcp@latest", "--sidekick-only"] } } }

Future direction: In a future version, XcodeMCP will transition to sidekick-only mode by default, focusing exclusively on tools that complement Apple's official Xcode MCP rather than duplicating functionality.

Development Setup

For local development:

git clone https://github.com/lapfelix/XcodeMCP.git

cd XcodeMCP npm install

Run in development mode (TypeScript)

npm run dev:ts

Or build and run compiled version

npm run build npm start

CLI Usage

XcodeMCP includes a powerful CLI that provides 100% feature parity with the MCP server, allowing you to run any tool as a one-shot command:

Installation

Install globally to use the CLI:

npm install -g xcodemcp

Basic Usage

# Show help and available tools

xcodecontrol --help

Run a tool with flags

xcodecontrol build --xcodeproj /path/to/Project.xcodeproj --scheme MyScheme

Get help for a specific tool

xcodecontrol build --help

Use JSON input instead of flags

xcodecontrol build --json-input '{"xcodeproj": "/path/to/Project.xcodeproj", "scheme": "MyScheme"}'

Output results in JSON format

xcodecontrol --json health-check

Path Resolution

The CLI supports both absolute and relative paths for convenience:

# Absolute paths (traditional)

xcodecontrol build --xcodeproj /Users/dev/MyApp/MyApp.xcodeproj --scheme MyApp

Relative paths (NEW in v2.0.0)

xcodecontrol build --xcodeproj MyApp.xcodeproj --scheme MyApp xcodecontrol build --xcodeproj ../OtherProject/OtherProject.xcodeproj --scheme OtherApp

Works with file paths too

xcodecontrol open-file --filePath src/ViewController.swift --lineNumber 42

Relative paths are resolved from your current working directory, making the CLI much more convenient to use when working within project directories.

Verbosity Control

Control logging output with verbosity flags:

# Verbose mode (shows INFO and DEBUG logs)

xcodecontrol -v build --xcodeproj /path/to/Project.xcodeproj --scheme MyScheme

Quiet mode (only errors)

xcodecontrol -q test --xcodeproj /path/to/Project.xcodeproj

Default mode (warnings and errors only)

xcodecontrol run --xcodeproj /path/to/Project.xcodeproj --scheme MyScheme

Quick Examples

# Check system health

xcodecontrol health-check

Build a project

xcodecontrol build --xcodeproj /Users/dev/MyApp/MyApp.xcodeproj --scheme MyApp

Run the app

xcodecontrol run --xcodeproj /Users/dev/MyApp/MyApp.xcodeproj --scheme MyApp

Run tests

xcodecontrol test --xcodeproj /Users/dev/MyApp/MyApp.xcodeproj

Clean build directory

xcodecontrol clean --xcodeproj /Users/dev/MyApp/MyApp.xcodeproj

Browse XCResult files

xcodecontrol xcresult-browse --xcresult-path /path/to/result.xcresult

Get UI hierarchy from test failure

xcodecontrol xcresult-get-ui-hierarchy --xcresult-path /path/to/result.xcresult --test-id "MyTest/testMethod()" --timestamp 30.5

Tool Name Mapping

CLI commands use kebab-case instead of underscores:

• xcode_build → build
• xcode_test → test
• xcode_build_and_run → build-and-run
• xcode_health_check → health-check
• xcresult_browse → xcresult-browse
• find_xcresults → find-xcresults

Available Tools

Project Management:

• xcode_open_project - Open projects and workspaces
• xcode_get_workspace_info - Get workspace status and details
• xcode_get_projects - List projects in workspace
• xcode_open_file - Open files with optional line number

Build Operations:

• xcode_build - Build with detailed error parsing
• xcode_clean - Clean build artifacts
• xcode_test - Run tests with optional arguments
• xcode_build_and_run - Build and run the active scheme
• xcode_debug - Start debugging session
• xcode_stop - Stop current operation

Configuration:

• xcode_get_schemes - List available schemes
• xcode_set_active_scheme - Switch active scheme
• xcode_get_run_destinations - List simulators and devices

XCResult Analysis:

• xcresult_browse - Browse test results and analyze failures
• xcresult_browser_get_console - Get console output for specific tests
• xcresult_summary - Quick overview of test results
• xcresult_get_screenshot - Extract screenshots from test failures
• xcresult_get_ui_hierarchy - Get UI hierarchy as AI-readable JSON with timestamp selection
• xcresult_get_ui_element - Get detailed properties of specific UI elements by index
• xcresult_list_attachments - List all attachments for a test
• xcresult_export_attachment - Export specific attachments from test results

Diagnostics:

• xcode_health_check - Environment validation and troubleshooting

XCResult Analysis Features

XcodeMCP provides comprehensive tools for analyzing Xcode test results (.xcresult files), making it easy to debug test failures and extract valuable information:

Test Result Analysis

• Browse Results: Navigate through test hierarchies, view pass/fail status, and examine detailed test information
• Console Logs: Extract console output and test activities with precise timestamps for debugging
• Quick Summaries: Get overview statistics including pass rates, failure counts, and duration

Visual Debugging

• Screenshot Extraction: Extract PNG screenshots from test failures using ffmpeg frame extraction from video attachments
• Timestamp Precision: Specify exact timestamps to capture UI state at specific moments during test execution

UI Hierarchy Analysis

• AI-Readable Format: Extract UI hierarchies as compressed JSON with single-letter properties (t=type, l=label, f=frame, c=children, j=index)
• Timestamp Selection: Automatically find the closest UI hierarchy capture to any specified timestamp
• Element Deep-Dive: Use index references to get full details of any UI element, including accessibility properties and frame information
• Size Optimization: 75%+ size reduction compared to full hierarchy data while maintaining all essential information

Attachment Management

• Complete Inventory: List all attachments (screenshots, videos, debug descriptions, UI hierarchies) for any test
• Selective Export: Export specific attachments by index or type
• Smart Detection: Automatically identify and categorize different attachment types

Usage Examples

# Browse test results

xcresult_browse "/path/to/TestResults.xcresult"

Get console output to find failure timestamps

xcresult_browser_get_console "/p