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

[npm version] [Test Status]

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

[Install in VS Code] [Install in VS Code Insiders] [Install MCP Server]

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 MCPclaude 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.gitcd XcodeMCPnpm install
# Run in development mode (TypeScript)npm run dev:ts
# Or build and run compiled versionnpm run buildnpm 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 toolsxcodecontrol --help
# Run a tool with flags  xcodecontrol build --xcodeproj /path/to/Project.xcodeproj --scheme MyScheme
# Get help for a specific toolxcodecontrol build --help
# Use JSON input instead of flagsxcodecontrol build --json-input '{"xcodeproj": "/path/to/Project.xcodeproj", "scheme": "MyScheme"}'
# Output results in JSON formatxcodecontrol --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 MyAppxcodecontrol build --xcodeproj ../OtherProject/OtherProject.xcodeproj --scheme OtherApp
# Works with file paths tooxcodecontrol 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 healthxcodecontrol health-check
# Build a projectxcodecontrol build --xcodeproj /Users/dev/MyApp/MyApp.xcodeproj --scheme MyApp
# Run the appxcodecontrol run --xcodeproj /Users/dev/MyApp/MyApp.xcodeproj --scheme MyApp
# Run testsxcodecontrol test --xcodeproj /Users/dev/MyApp/MyApp.xcodeproj
# Clean build directoryxcodecontrol clean --xcodeproj /Users/dev/MyApp/MyApp.xcodeproj
# Browse XCResult filesxcodecontrol xcresult-browse --xcresult-path /path/to/result.xcresult
# Get UI hierarchy from test failurexcodecontrol 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 resultsxcresult_browse "/path/to/TestResults.xcresult"
# Get console output to find failure timestampsxcresult_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 elementxcresult_get_ui_element "/path/to/ui_hierarchy_full.json" 15
# Extract screenshot at failure pointxcresult_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:

   bash

   which xclogparserxclogparser version

2. Common issues and solutions:

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

     bash

     # For Homebrew on Intel Macsexport PATH="/usr/local/bin:$PATH"
     # For Homebrew on Apple Silicon Macsexport 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:

     bash

     chmod +x $(which xclogparser)

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

   bash

   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