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:

Install from npm

Run directly with npx:

Or install globally:

MCP Configuration

Add to your MCP configuration:

Claude Code CLI Setup

To add XcodeMCP to Claude Code using the command line:

Without the clean build folder tool

To add XcodeMCP to Claude Code using the command line:

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:

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

Development Setup

For local development:

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:

Basic Usage

Path Resolution

The CLI supports both absolute and relative paths for convenience:

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:

Quick Examples

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

Configuration

Logging Configuration

XcodeMCP supports configurable logging to help with debugging and monitoring:

Environment Variables

• LOG_LEVEL: Controls logging verbosity (default: INFO)

  • SILENT: No logging output

  • ERROR: Only error messages

  • WARN: Warnings and errors

  • INFO: General operational information (recommended)

  • DEBUG: Detailed diagnostic information

• XCODEMCP_LOG_FILE: Optional file path for logging

  • Logs are written to the specified file in addition to stderr

  • Parent directories are created automatically

  • Example: /tmp/xcodemcp.log or ~/Library/Logs/xcodemcp.log

• XCODEMCP_CONSOLE_LOGGING: Enable/disable console output (default: true)

  • Set to false to disable stderr logging (useful when using file logging only)

Examples

Debug logging with file output:

Silent mode (no logging):

File-only logging:

All logs are properly formatted with timestamps and log levels, and stderr output maintains compatibility with the MCP protocol.

Troubleshooting

XCLogParser Not Found

If you see a warning that XCLogParser is not found even though it's installed:

1. Verify installation:

   which xclogparser xclogparser version

2. Common issues and solutions:

   • PATH issue: If which xclogparser returns nothing, add the installation directory to your PATH:

     # For Homebrew on Intel Macs export PATH="/usr/local/bin:$PATH" # For Homebrew on Apple Silicon Macs export PATH="/opt/homebrew/bin:$PATH"

   • Wrong command: Older documentation may reference xclogparser --version, but the correct command is xclogparser version (without dashes)

   • Permission issue: Ensure xclogparser is executable:

     chmod +x $(which xclogparser)

3. Environment validation: Run the health check to get detailed diagnostics:

   echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "xcode_health_check", "arguments": {}}}' | npx xcodemcp

Note: XcodeMCP can operate without XCLogParser, but build error parsing will be limited.

Example Output

Build with errors:

Health check: