XcodeMCP

XcodeMCP

Model Context Protocol (MCP) server that controls Xcode directly through JavaScript for Automation (JXA).

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

Requirements

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

Usage

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": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

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": {
    "LOG_LEVEL": "INFO"
  }
}'

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

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_run - 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 "/path/to/TestResults.xcresult" "MyTest/testMethod()"

# Get UI hierarchy at specific timestamp (AI-readable slim version)
xcresult_get_ui_hierarchy "/path/to/TestResults.xcresult" "MyTest/testMethod()" 45.25

# Get full UI hierarchy (with size warning)
xcresult_get_ui_hierarchy "/path/to/TestResults.xcresult" "MyTest/testMethod()" 45.25 true

# Get detailed properties of a specific UI element
xcresult_get_ui_element "/path/to/ui_hierarchy_full.json" 15

# Extract screenshot at failure point
xcresult_get_screenshot "/path/to/TestResults.xcresult" "MyTest/testMethod()" 30.71

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:

{
  "mcpServers": {
    "xcodemcp": {
      "command": "npx",
      "args": ["-y", "xcodemcp@latest"],
      "env": {
        "LOG_LEVEL": "DEBUG",
        "XCODEMCP_LOG_FILE": "~/Library/Logs/xcodemcp.log"
      }
    }
  }
}

Silent mode (no logging):

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

File-only logging:

{
  "mcpServers": {
    "xcodemcp": {
      "command": "npx",
      "args": ["-y", "xcodemcp@latest"], 
      "env": {
        "LOG_LEVEL": "INFO",
        "XCODEMCP_LOG_FILE": "/tmp/xcodemcp.log",
        "XCODEMCP_CONSOLE_LOGGING": "false"
      }
    }
  }
}

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:

❌ BUILD FAILED (2 errors)

ERRORS:
  • /path/HandsDownApp.swift:7:18: Expected 'func' keyword in instance method declaration
  • /path/MenuBarManager.swift:98:13: Invalid redeclaration of 'toggleItem'

Health check:

✅ All systems operational

✅ OS: macOS environment detected
✅ XCODE: Xcode found at /Applications/Xcode.app (version 16.4)
✅ XCLOGPARSER: XCLogParser found (XCLogParser 0.2.41)
✅ OSASCRIPT: JavaScript for Automation (JXA) is available
✅ PERMISSIONS: Xcode automation permissions are working