Skip to main content
Glama

XcodeMCP

by lapfelix
npmGitHub
TypeScript
Apache 2.0
656
27
  • Apple
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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": { "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

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_run → 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_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
Install Server
A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

Tools

View all tools

MCP server for Xcode build automation and log parsing that opens Xcode projects, triggers builds directly in Xcode, and parses build logs to extract errors and warnings.

  1. What it does
    1. Requirements
      1. Usage
        1. Quick Install
        2. Install from npm
        3. MCP Configuration
        4. Claude Code CLI Setup
        5. Development Setup
      2. CLI Usage
        1. Installation
        2. Basic Usage
        3. Path Resolution
        4. Verbosity Control
        5. Quick Examples
        6. Tool Name Mapping
      3. Available Tools
        1. XCResult Analysis Features
          1. Test Result Analysis
          2. Visual Debugging
          3. UI Hierarchy Analysis
          4. Attachment Management
          5. Usage Examples
        2. Configuration
          1. Logging Configuration
        3. Troubleshooting
          1. XCLogParser Not Found
        4. Example Output

          Related MCP Servers

          • MCP Server Neurolorap

            aindreyway
            A
            security
            A
            license
            A
            quality
            MCP server for collecting code from files and directories into a single markdown document.
            Last updated -
            2
            4
            Python
            MIT License

          • Project Content Server

            MaheshDoiphode
            A
            security
            A
            license
            A
            quality
            An MCP server that provides access to project files and their contents, allowing users to retrieve file data from specified project directories with error handling and configuration options.
            Last updated -
            1
            4
            TypeScript
            MIT License

          • Lodestar MCP Server

            kanlanc
            -
            security
            F
            license
            -
            quality
            This is an MCP server that facilitates building tools for interacting with various APIs and workflows, supporting Python-based development with potential for customizable prompts and user configurations.
            Last updated -
            Python

          • MCP Project Orchestrator

            sparesparrow
            -
            security
            A
            license
            -
            quality
            An MCP server that assists with the orchestration of new software projects by applying standardized templates and best practices in design patterns and software architecture.
            Last updated -
            3
            Python
            MIT License
            • Apple

          View all related MCP servers

          New MCP Servers

          MCP directory API

          We provide all the information about MCP servers via our MCP API.

          curl -X GET 'https://glama.ai/api/mcp/v1/servers/lapfelix/XcodeMCP'

          If you have feedback or need assistance with the MCP directory API, please join our Discord server