XcodeMCP

Apple の公式 Xcode MCP との併用：Apple は現在、公式の Xcode MCP サーバーを提供しています。XcodeMCP はサイドキックモード（--sidekick-only）で同時に実行でき、プロジェクト管理や XCResult 分析などの補完的なツールを提供します。今後のバージョンでは、XcodeMCP はデフォルトでサイドキック専用モードに移行する予定です。以下の設定を参照してください。

XcodeMCP

JavaScript for Automation（JXA）を通じて Xcode を直接操作する Model Context Protocol（MCP）サーバーです。MCP サーバーとスタンドアロンの CLI の両方で利用できます。

機能

• JavaScript for Automation を通じて Xcode を直接操作します（xcodebuild CLI は使用しません）
• Xcode 内からプロジェクトを開き、ビルド、実行、テスト、デバッグを行います
• XCLogParser を使用して、正確なエラー箇所を含むビルドログを解析します
• 包括的な環境検証とヘルスチェックを提供します
• オプションの依存関係が見つからない場合も、機能を適切に縮退させて動作します
• 新機能：MCP サーバーと 100％の機能互換性を備えたフル機能の CLI を搭載しています

必要条件

• Xcode がインストールされた macOS
• Node.js 18+
• XCLogParser（推奨）：brew install xclogparser

使い方

XcodeMCP は次の 2 つの方法で使用できます。

1. MCP サーバー：Claude Desktop、VS Code、その他の MCP クライアントと連携します
2. CLI ツール：xcodecontrol を使って、ターミナルから直接コマンドを実行します

クイックインストール

XCLogParser は推奨されていますが、必須ではありません。

brew install xclogparser

npm からインストール

npx で直接実行します。

npx -y xcodemcp@latest

または、グローバルにインストールします。

npm install -g xcodemcp

MCP の設定

MCP の設定に追加します。

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

Claude Code CLI のセットアップ

コマンドラインを使って XcodeMCP を Claude Code に追加します。

claude mcp add-json XcodeMCP '{
  "command": "npx",
  "args": ["-y", "xcodemcp@latest"],
  "env": {
  }
}'

クリーンビルドフォルダツールを使わない場合

コマンドラインを使って XcodeMCP を Claude Code に追加します。

claude mcp add-json XcodeMCP '{
  "command": "npx",
  "args": ["-y", "xcodemcp@latest", "--no-clean"],
  "env": {
  }
}'

単一プロジェクトのワークフローで優先値を使用する

単一の xcodeproj とスキームを扱うプロジェクトでは、優先値を設定してツールのパラメーターを省略可能にできます。

claude mcp add-json XcodeMCP '{
  "command": "npx",
  "args": ["-y", "xcodemcp@latest"],
  "env": {
    "XCODE_MCP_PREFERRED_SCHEME": "MyApp",
    "XCODE_MCP_PREFERRED_XCODEPROJ": "MyApp.xcodeproj"
  }
}'

優先値を設定すると、次のようになります。

• ツールのパラメーターが必須ではなく、省略可能になります
• ツールの説明にデフォルト値が表示されます（例：「デフォルトは MyApp.xcodeproj」）
• 明示的なパラメーターを指定すれば、デフォルト値を引き続き上書きできます
• 単一のプロジェクトを扱う際の繰り返しを減らせます

トラブルシューティング

Claude Code の /mcp で MCP が失敗したと表示される場合は、出力を確認するため、プロジェクトフォルダから手動で実行してみてください：npx -y xcodemcp@latest

Sidekick Mode

Apple公式のXcode MCPサーバーとXcodeMCPを併用する場合は、補完的なツールのみを含めるためにサイドキックモードを有効にしてください。

• プロジェクト管理：プロジェクトの開閉、スキームの管理、ワークスペース情報の取得
• XCResult分析：テスト結果の閲覧、スクリーンショットの抽出、UI階層の確認

これにより、AppleのMCPがネイティブに処理するビルド／実行／テスト／デバッグツールは除外されます。

Claude Code CLI Setup (Both Servers)

まず、Xcode > Settings > Intelligence > Model Context ProtocolでXcode Toolsを有効にします。

次に、AppleのXcode MCPとXcodeMCPの両方をサイドキックモードで追加します。

# Add Apple's official Xcode MCP
claude 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"]
    }
  }
}

今後の方針：将来のバージョンでは、XcodeMCPはデフォルトでサイドキック専用モードに移行し、機能を重複させるのではなく、Apple公式のXcode MCPを補完するツールのみに注力します。

Development Setup

ローカル開発の場合：

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には、MCPサーバーと100％の機能同等性を備えた強力なCLIが含まれており、任意のツールを単発のコマンドとして実行できます。

Installation

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

利便性のため、CLIでは絶対パスと相対パスの両方をサポートしています。

# 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

相対パスは現在の作業ディレクトリを基準に解決されるため、プロジェクトディレクトリ内で作業する際にCLIをより便利に使用できます。

Verbosity Control

詳細度フラグでログ出力を制御します。

# 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コマンドでは、アンダースコアの代わりにケバブケースを使用します。

• 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

プロジェクト管理：

• xcode_open_project - プロジェクトとワークスペースを開く
• xcode_get_workspace_info - ワークスペースの状態と詳細を取得
• xcode_get_projects - ワークスペース内のプロジェクトを一覧表示
• xcode_open_file - オプションで行番号を指定してファイルを開く

ビルド操作：

• xcode_build - 詳細なエラー解析を行いながらビルド
• xcode_clean - ビルド成果物をクリーンアップ
• xcode_test - オプションの引数を指定してテストを実行
• xcode_build_and_run - アクティブなスキームをビルドして実行
• xcode_debug - デバッグセッションを開始
• xcode_stop - 現在の操作を停止

設定：

• xcode_get_schemes - 使用可能なスキームを一覧表示
• xcode_set_active_scheme - アクティブなスキームを切り替え
• xcode_get_run_destinations - シミュレーターとデバイスを一覧表示

XCResult分析：

• xcresult_browse - テスト結果を閲覧し、失敗を分析
• xcresult_browser_get_console - 特定のテストのコンソール出力を取得
• xcresult_summary - テスト結果の概要をすばやく表示
• xcresult_get_screenshot - テスト失敗時のスクリーンショットを抽出
• xcresult_get_ui_hierarchy - タイムスタンプを選択して、AIが読み取れるJSON形式でUI階層を取得
• xcresult_get_ui_element - インデックスを指定して特定のUI要素の詳細なプロパティを取得
• xcresult_list_attachments - テストのすべての添付ファイルを一覧表示
• xcresult_export_attachment - テスト結果から特定の添付ファイルをエクスポート

診断：

• xcode_health_check - 環境の検証とトラブルシューティング

XCResult Analysis Features

XcodeMCPは、Xcodeテスト結果（.xcresultファイル）を分析するための包括的なツールを提供しており、テストの失敗をデバッグして有用な情報を抽出できます。

Test Result Analysis

• 結果の閲覧：テスト階層をたどり、合否の状態を確認し、詳細なテスト情報を調べます
• コンソールログ：デバッグ用に、正確なタイムスタンプ付きでコンソール出力とテストアクティビティを抽出します
• クイックサマリー：合格率、失敗件数、所要時間などの概要統計を取得します

ビジュアルデバッグ

• スクリーンショットの抽出：動画の添付ファイルから ffmpeg でフレームを抽出し、テスト失敗時の PNG スクリーンショットを取得します
• タイムスタンプの精度：テスト実行中の特定の時点の UI 状態をキャプチャするため、正確なタイムスタンプを指定できます

UI 階層の分析

• AI が読み取れる形式：1 文字のプロパティ（t=タイプ、l=ラベル、f=フレーム、c=子要素、j=インデックス）を使用した圧縮 JSON として、UI 階層を抽出します
• タイムスタンプの選択：指定したタイムスタンプに最も近い UI 階層のキャプチャを自動的に検索します
• 要素の詳細確認：インデックス参照を使って、アクセシビリティプロパティやフレーム情報を含む UI 要素の詳細を取得します
• サイズの最適化：必要な情報をすべて保持しながら、完全な階層データと比較してサイズを 75％以上削減します

添付ファイルの管理

• 完全な一覧：任意のテストに含まれるすべての添付ファイル（スクリーンショット、動画、デバッグ説明、UI 階層）を一覧表示します
• 選択的なエクスポート：インデックスまたはタイプを指定して、特定の添付ファイルをエクスポートします
• スマート検出：さまざまな添付ファイルのタイプを自動的に識別して分類します

使用例

# 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

設定

ログの設定

XcodeMCP は、デバッグや監視に役立つログ設定をサポートしています。

環境変数

• LOG_LEVEL：ログの詳細度を制御します（デフォルト：INFO）

  • SILENT：ログを出力しません
  • ERROR：エラーメッセージのみ
  • WARN：警告とエラー
  • INFO：一般的な運用情報（推奨）
  • DEBUG：詳細な診断情報

• XCODEMCP_LOG_FILE：ログ出力先のオプションのファイルパス

  • stderr に加えて、指定したファイルにもログを書き込みます
  • 親ディレクトリは自動的に作成されます
  • 例：/tmp/xcodemcp.log または ~/Library/Logs/xcodemcp.log

• XCODEMCP_CONSOLE_LOGGING：コンソール出力を有効または無効にします（デフォルト：true）

  • stderr へのログ出力を無効にするには、false に設定します（ファイルへのログ出力のみを使用する場合に便利です）

例

ファイル出力を伴うデバッグログ：

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

サイレントモード（ログ出力なし）：

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

ファイルへのログ出力のみ：

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

すべてのログはタイムスタンプとログレベルを含む適切な形式で出力され、stderr への出力は MCP プロトコルとの互換性を維持します。

トラブルシューティング

XCLogParser が見つからない

インストール済みであるにもかかわらず、XCLogParser が見つからないという警告が表示される場合：

1. インストールを確認する：

   which xclogparser
   xclogparser version
   

2. よくある問題と解決方法：

   • PATH の問題：which xclogparser を実行して何も返されない場合は、インストールディレクトリを PATH に追加します。

     # Intel Mac で Homebrew を使用する場合
     export PATH="/usr/local/bin:$PATH"
     
     # Apple Silicon Mac で Homebrew を使用する場合
     export PATH="/opt/homebrew/bin:$PATH"
     

   • コマンドの誤り：古いドキュメントでは xclogparser --version と記載されていることがありますが、正しいコマンドは xclogparser version です（ダッシュは付けません）。

   • 権限の問題：xclogparser に実行権限があることを確認します。

     chmod +x $(which xclogparser)
     

3. 環境の検証：ヘルスチェックを実行して、詳細な診断情報を取得します。

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

注：XcodeMCP は XCLogParser がなくても動作しますが、ビルドエラーの解析は制限されます。

出力例

エラーのあるビルド：

❌ 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'

ヘルスチェック：

✅ 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