Xcode Instruments CLI

XCTools MCP Server

xcrun、xcodebuild、xctrace などの Xcode 開発ツールに構造化された方法でアクセスできる Model Context Protocol（MCP）サーバーです。

インストール

方法 1：uvx を使用する

1. 前提条件：

   • Python 3.13+
   • Command Line Tools がインストールされた Xcode
   • uvx：curl -LsSf https://astral.sh/uv/install.sh | sh

2. uvx で直接実行する：

   uvx xctools-mcp-server
   

方法 2：ローカル開発環境へのインストール

1. 前提条件：

   • Python 3.13+
   • Command Line Tools がインストールされた Xcode

2. クローンしてインストールする：

   git clone https://github.com/nzrsky/xctools-mcp-server
   cd xctools-mcp-server
   pip install .
   

3. サーバーを実行する：

   xctools-mcp-server
   

方法 3：ソースからビルドする

1. wheel をビルドする：

   python -m build --wheel
   pip install dist/xctools_mcp_server-0.1.0-py3-none-any.whl
   

設定

Claude Desktop の場合

~/Library/Application Support/Claude/claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "xctools": {
      "command": "xctools-mcp-server",
      "args": [],
      "env": {}
    }
  }
}

uvx を使用する場合：

{
  "mcpServers": {
    "xctools": {
      "command": "uvx",
      "args": ["xctools-mcp-server"],
      "env": {}
    }
  }
}

MCP Extension を使用した VS Code の場合

1. VS Code マーケットプレイスから MCP Extension をインストールします
2. VS Code の設定（settings.json）にサーバー設定を追加します：

{
  "mcp.servers": {
    "xctools": {
      "command": "xctools-mcp-server",
      "args": [],
      "env": {}
    }
  }
}

uvx を使用する場合：

{
  "mcp.servers": {
    "xctools": {
      "command": "uvx",
      "args": ["xctools-mcp-server"],
      "env": {}
    }
  }
}

3. MCP サーバーを読み込むためにVS Code を再起動します
4. コマンドパレット（Cmd+Shift+P）を開き、「MCP」コマンドを検索して Xcode 開発ツールを操作します

その他の MCP クライアントの場合

このサーバーは stdio で動作するため、直接呼び出すことができます：

インストール済みパッケージを使用する場合：

xctools-mcp-server

uvx を使用する場合：

uvx xctools-mcp-server

機能

• xcrun を通じたXcode ツールチェーンへの完全なアクセス
• xcodebuild によるプロジェクトのビルドとテスト
• xctrace（Instruments）を使用したパフォーマンス分析
• SDK と実行先の管理
• 詳細なメッセージによる包括的なエラー処理
• クロスプラットフォーム互換性（Xcode がインストールされた macOS）

利用可能なツール

XCRUN ツール

• xcrun_find_tool - 開発ツール（clang、swift など）のパスを検索します
• xcrun_show_sdk_path - SDK のパスを表示します
• xcrun_show_sdk_version - SDK のバージョンを表示します
• xcrun_run_tool - xcrun 経由で任意の開発ツールを実行します

XCODEBUILD ツール

• xcodebuild_build - Xcode プロジェクトまたはワークスペースをビルドします
• xcodebuild_test - プロジェクト／ワークスペースのテストを実行します
• xcodebuild_archive - 配布用にプロジェクトをアーカイブします
• xcodebuild_list - ターゲット、スキーム、構成を一覧表示します
• xcodebuild_show_sdks - 利用可能な SDK をすべて一覧表示します
• xcodebuild_show_destinations - 有効なビルド先を表示します

XCTRACE ツール（Instruments）

• xctrace_record - 新しい Instruments トレースを記録します
• xctrace_import - 対応ファイルをトレース形式にインポートします
• xctrace_export - トレースファイルからデータをエクスポートします
• xctrace_list - 利用可能なデバイス、テンプレート、または Instruments を一覧表示します
• xctrace_symbolicate - デバッグシンボルを使ってトレースをシンボリケートします

使用例

開発ツールを検索する

# Find the path to a specific tool
"Find the path to clang compiler"

# Show SDK path for iOS
"Show the path to the iOS SDK"

# Get SDK version information
"Show the version of the iOS SDK"

プロジェクトをビルドする

# Build an Xcode project
"Build the project MyApp.xcodeproj for iOS simulator"

# Run tests for a workspace
"Run tests for MyApp.xcworkspace on iPhone 15 Pro simulator"

# Archive for distribution
"Archive MyApp.xcworkspace for release"

# List project information
"List all schemes and targets in MyApp.xcodeproj"

Instruments でパフォーマンスを分析する

# Record a trace for Time Profiler
"Record a Time Profiler trace for MyApp on iPhone 15 Pro for 30 seconds"

# List available instruments
"List all available Instruments templates"

# Export trace data
"Export data from trace file to XML format"

# Import a file for analysis
"Import a .dtps file into Instruments trace format"

SDK と実行先を管理する

# List all available SDKs
"Show all available SDKs for building"

# Show build destinations
"List all available destinations for iOS builds"

# Run a tool via xcrun
"Run swift command with version flag via xcrun"

エラー処理

このサーバーには、包括的なエラー処理が含まれています：

• コマンドの失敗：xcrun、xcodebuild、xctrace から詳細なエラーメッセージを返します
• Xcode が見つからない場合：Xcode Command Line Tools を利用できない場合に検出します
• 無効なパラメーター：ツールの引数を検証し、役立つエラーメッセージを表示します
• ツールの利用可否：実行前に必要なツールがあるか確認します

トラブルシューティング

よくある問題

1. 「xcrun: error: unable to find utility」

   • Xcode Command Line Tools がインストールされていることを確認します：xcode-select --install
   • Xcode が正しく設定されていることを確認します：xcode-select -p

2. 「No developer directory found」

   • Mac App Store から Xcode をインストールします
   • Xcode のライセンスに同意します：sudo xcodebuild -license accept

3. 権限エラー

   • ユーザーに Xcode ツールへのアクセスに必要な権限があることを確認します
   • 適切な macOS 開発権限で実行してみます

4. ツールが見つからないエラー

   • 使用するツールが Xcode のインストールに含まれていることを確認します
   • ツールによっては、特定の Xcode バージョンや追加コンポーネントが必要な場合があります

要件

• macOS：必須（Xcode 開発ツールは macOS 専用です）
• Xcode：Xcode Command Line Tools または Xcode のフルインストール
• Python：3.13 以降
• MCP クライアント：Claude Desktop、MCP 拡張機能を備えた VS Code、またはその他の MCP 互換クライアント

コントリビューション

コントリビューションを歓迎します！お気軽に Pull Request を送信してください。

ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細は LICENSE ファイルをご覧ください。

• 無効なパラメーター：実行前に入力パラメーターを検証します
• ファイル操作：プッシュ通知用の一時ファイルを安全に処理します

セキュリティに関する考慮事項

• サーバーが公開するのは、読み取り操作とシミュレーターの管理操作のみです
• 指定されたアプリのパス以外では、ホストのファイルシステムにアクセスしません
• プッシュ通知のペイロードは構造を検証します
• プライバシー権限の変更は明示的に行われ、ログに記録されます

開発上の注意

• iOS 開発のワークフロー専用に構築されています
• 一般的なシミュレーター管理タスク向けに最適化されています
• JSON レスポンスを構造化して解析します
• 個別操作と一括操作の両方をサポートします
• Xcode 15 以降のシミュレーター機能に対応しています