Xcodebuildmcp

🚀 XcodeBuildMCP

このプロジェクトは、MCP（Model Context Protocol）サーバーを実装しており、Xcodeの操作をツールとして公開します。これらのツールは、MCPプロトコルを介してAIエージェントによって呼び出すことができます。標準化されたインターフェースを通じて、Xcodeプロジェクトとのプログラムによる対話を可能にし、エージェント主導の開発ワークフローに最適化されています。

🚀 クイックスタート

概要

このプロジェクトは、MCPサーバーを実装しており、Xcodeの操作をツールとして公開します。これらのツールは、MCPプロトコルを介してAIエージェントによって呼び出すことができます。標準化されたインターフェースを通じて、Xcodeプロジェクトとのプログラムによる対話を可能にし、エージェント主導の開発ワークフローに最適化されています。

なぜこのツールが必要なのか？

XcodeBuild MCPツールは、主にAIエージェントとXcodeプロジェクトとの間のやり取りを合理化および標準化するために存在します。一般的なXcode操作に対する専用ツールを提供することで、手動または潜在的に誤ったコマンドライン呼び出しへの依存を排除します。

これにより、信頼性の高い効率的な開発プロセスが保証され、エージェントがXcodeの機能をシームレスに活用できるようになり、構成エラーのリスクが軽減されます。

重要なことに、このMCPにより、AIエージェントはプロジェクトをビルドし、エラーを検査し、自律的に反復することで、コード変更を独自に検証できるようになります。Sweetpadのようなユーザー主導のツールとは対照的に、XcodeBuild MCPはエージェントがこれらのワークフローを効果的に自動化できるようにします。

前提条件

• macOS 14.5以上
• Xcode 16.x以上
• Node 18.x以上
• AXe 1.0.0以上（UI自動化に必要で、オプション）

UI自動化

UI自動化機能（タップ、スワイプ、入力など）を使用するには、AXeをインストールする必要があります。

brew tap cameroncooke/axe
brew install axe

AXeに関する詳細情報と他のインストール方法については、AXeリポジトリを参照してください。

MCPクライアントの設定

クイックインストール

クイックインストールには、以下のリンクを使用できます。

手動インストール

MCPクライアント（Windsurf、Cursor、Claude Desktop、Claude Codeなど）を構成して、XcodeBuildMCPサーバーを使用するには、クライアントアプリケーションのMCP構成を修正します。

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "npx",
      "args": [
        "-y",
        "xcodebuildmcp@latest"
      ]
    }
  }
}

miseを使用した代替インストール方法

あるいは、miseを使用して、Node.jsを特定のインストールなしでXcodeBuildMCPを使用することができます。

# macOS (Homebrew)
brew install mise

# 他のインストール方法
# https://mise.jdx.dev/getting-started.html を参照

次に、MCPクライアントを構成して、miseを使用してXcodeBuildMCPをインストールします。

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "mise",
      "args": [
        "x",
        "npm:xcodebuildmcp@1.7.0",
        "--",
        "xcodebuildmcp"
      ]
    }
  }
}

⚠️ 重要提示

miseを使用する場合は、@latestタグの使用を避けてください。miseはパッケージをキャッシュするため、自動的に最新バージョンに更新されない可能性があります。代わりに、明示的なバージョン番号を使用することを推奨します。

⚠️ 重要提示

XcodeBuildMCPは、xcodebuildにマクロ検証をスキップするよう要求します。これは、Swiftマクロを使用するプロジェクトをビルドする際のエラーを回避するためです。

✨ 主な機能

Xcodeプロジェクト管理

• プロジェクトの探索：Xcodeプロジェクトとワークスペースの探索
• ビルド操作：macOS、iOSシミュレーター、iOSデバイスターゲット用のプラットフォーム固有のビルドツール
• プロジェクト情報：Xcodeプロジェクトとワークスペースのスキームをリストし、ビルド設定を表示するツール
• クリーン操作：xcodebuildのネイティブクリーンアクションを使用してビルド生成物をクリーンアップ
• インクリメンタルビルドのサポート：インクリメンタルビルドのサポートを使用した高速ビルド（実験的機能、オプトインが必要）
• プロジェクトのスカフォールディング：ワークスペース+SPMパッケージアーキテクチャ、カスタマイズ可能なバンドル識別子、デプロイメントターゲット、デバイスファミリーを持つ、最新のテンプレートから新しいiOSおよびmacOSプロジェクトを作成

Swiftパッケージマネージャー

• パッケージのビルド：構成とアーキテクチャオプションを使用してSwiftパッケージをビルド
• テストの実行：フィルタリングと並列実行を使用してSwiftパッケージのテストスイートを実行
• 実行可能ファイルの実行：タイムアウト処理とバックグラウンド実行のサポートを持つパッケージバイナリを実行
• プロセス管理：Swiftパッケージツールで起動された長時間実行される実行可能ファイルをリストし、停止する
• アーティファクトのクリーンアップ：新しいビルドのためにビルドアーティファクトと派生データを削除

シミュレーター管理

• シミュレーターの制御：iOSシミュレーターをリスト、起動、開く
• アプリのデプロイ：iOSシミュレーターにアプリをインストールし、起動する
• ログのキャプチャ：シミュレーターから実行時のログをキャプチャする
• UI自動化：シミュレーターのUI要素と対話する（ベータ版）
• スクリーンショット：シミュレーターからスクリーンショットをキャプチャする（ベータ版）

アプリユーティリティ

• バンドルIDの抽出：iOSおよびmacOSアプリバンドルからバンドル識別子を抽出する
• アプリの起動：シミュレーターとmacOSの両方でビルドされたアプリケーションを起動する

📦 インストール

インクリメンタルビルドのサポート

XcodeBuildMCPには、インクリメンタルビルドの実験的なサポートが含まれています。この機能はデフォルトで無効になっており、INCREMENTAL_BUILDS_ENABLED環境変数をtrueに設定することで有効にできます。

インクリメンタルビルドを有効にするには、INCREMENTAL_BUILDS_ENABLED環境変数をtrueに設定します。

例のMCPクライアント構成：

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "npx",
      "args": [
        "-y",
        "xcodebuildmcp@latest"
      ],
      "env": {
        "INCREMENTAL_BUILDS_ENABLED": "true"
      }        
    }
  }
}

⚠️ 重要提示

インクリメンタルビルドのサポートは現在高度に実験的なものであり、結果は異なる場合があります。遭遇した問題はすべて、問題トラッカーに報告してください。

🔧 技術詳細

トラブルシューティング

XcodeBuildMCPで問題が発生した場合、診断ツールを使用して、環境と依存関係に関する詳細情報を提供することで問題を特定できます。

診断ツール

診断ツールは、システム構成をチェックし、XcodeBuildMCPに必要なすべての依存関係の状態を報告するスタンドアロンのユーティリティです。問題を報告する際に特に役立ちます。

npxを使用する場合

# npxを使用して診断ツールを実行
npx xcodebuildmcp@1.7.0 xcodebuildmcp-diagnostic

miseを使用する場合

# miseを使用して診断ツールを実行
mise x npm:xcodebuildmcp@1.7.0 -- xcodebuildmcp-diagnostic

診断ツールは、以下に関する包括的な情報を出力します。

• システムとNode.js環境
• Xcodeのインストールと構成
• 必要な依存関係（xcodebuild、AXeなど）
• XcodeBuildMCPに影響を与える環境変数
• 機能の利用可能状態

GitHubで問題を報告する際には、トラブルシューティングを支援するために、診断ツールからの完全な出力を含めてください。

MCPサーバーのログ

MCPサーバーのログメッセージにアクセスすると、問題を特定するのに役立つ場合があります。ログはクライアントアプリケーションによってキャプチャされます。例えば、Cursorでは以下のようになります。

Cursor:

find ~/Library/Application\ Support/Cursor/logs -name "Cursor MCP.log" -exec zip -r matching_logs.zip {} +

MCPクライアントにログファイルがない場合は、MCPインスペクターツールを使用してサーバーを直接実行できます。詳細については、デバッグを参照してください。MCPツールを実行すると、すべてのログメッセージがエラーペインに表示され、問題の診断に役立ちます。

プライバシー

このプロジェクトは、エラー監視と診断にSentryを使用しています。Sentryは、問題、クラッシュ、予期しないエラーを追跡し、XcodeBuildMCPの信頼性と安定性を向上させるのに役立ちます。

Sentryに送信されるもの

• デフォルトでは、エラーレベルのログと診断情報のみがSentryに送信されます。
• エラーログには、エラーメッセージ、スタックトレース、場合によってはファイルパスやプロジェクト名などの詳細が含まれる場合があります。正確に何がログに記録されているかを確認するには、このリポジトリのソースを確認してください。

Sentryの利用を拒否する

• エラーログをSentryに送信したくない場合は、SENTRY_DISABLED=true環境変数を設定することで拒否できます。

例のMCPクライアント構成：

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "npx",
      "args": [
        "-y",
        "xcodebuildmcp@latest"
      ],
      "env": {
        "SENTRY_DISABLED": "true"
      }        
    }
  }
}

選択的なツール登録

デフォルトではすべてのツールが有効になっていますが、一部のクライアントでは、特定のツールのみを有効にして、クライアントに送信されるコンテキストの量を減らすことが有用な場合があります。これは、クライアントのMCP構成で特定の環境変数を設定することで実現できます。

1つ以上のツールまたはツールグループを有効にすると、他のすべてのツールは無効になります。例えば、iOSシミュレーター関連のツールのみを有効にするには、XCODEBUILDMCP_GROUP_IOS_SIMULATOR_WORKFLOW=true環境変数を設定します。これにより、シミュレーター上でのビルド、実行、デバッグ用のツールのみが公開されます。

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "npx",
      "args": [
        "-y",
        "xcodebuildmcp@latest"
      ],
      "env": {
        "XCODEBUILDMCP_GROUP_IOS_SIMULATOR_WORKFLOW": "true"
      }        
    }
  }
}

利用可能なツールのリストと、それらを有効にする方法の詳細な手順については、TOOL_OPTIONS.mdファイルを参照してください。

📚 ドキュメント

デモ

Cursorでビルドエラーを自律的に修正する

新しいUI自動化とスクリーンキャプチャ機能を活用する

Claude DesktopでiOSアプリをビルドして実行する

https://github.com/user-attachments/assets/e3c08d75-8be6-4857-b4d0-9350b26ef086

コントリビュート

コントリビューションは大歓迎です！XcodeBuildMCPを改善するために、以下の方法でお手伝いいただけます。

詳細な情報や、ローカル環境の設定方法、プロジェクトへのコントリビュート方法については、CONTRIBUTINGドキュメントを参照してください。

📄 ライセンス

このプロジェクトは、MITライセンスの下でライセンスされています。詳細については、LICENSEファイルを参照してください。

MCPサーバーの検証

Glama.ai

MseeP.a