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:

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:

Development Setup

For local development:

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

Diagnostics:

• xcode_health_check - Environment validation and troubleshooting

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: