XcodeBuildMCP

AI アシスタントやその他の MCP クライアントとの統合のための Xcode 関連ツールを提供するモデルコンテキストプロトコル (MCP) サーバー。

概要
なぜ？
特徴
はじめる
増分ビルドのサポート
トラブルシューティング
- 診断ツール
  - miseと一緒に使う
  - npx での使用
- MCP サーバーログ
プライバシー
- Sentry には何が送信されますか?
- Sentryからのオプトアウト
選択ツール登録
デモ
貢献
ライセンス

概要

このプロジェクトは、Xcodeの操作をMCPプロトコル経由でAIエージェントから呼び出せるツールとして公開するMCPサーバーを実装します。エージェント駆動型開発ワークフローに最適化された標準化されたインターフェースを通じて、Xcodeプロジェクトとのプログラムによるインタラクションを可能にします。

なぜ？

XcodeBuild MCPツールは、AIエージェントとXcodeプロジェクト間のインタラクションを効率化・標準化することを主な目的としています。一般的なXcode操作専用のツールを提供することで、手動または不正確な可能性のあるコマンドライン呼び出しへの依存を排除します。

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

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

特徴

XcodeBuildMCP サーバーは、次のツール機能を提供します。

Xcodeプロジェクト管理

プロジェクトの検出: Xcode プロジェクトとワークスペースの検出
ビルド操作: macOS、iOS シミュレータ、iOS デバイスターゲット用のプラットフォーム固有のビルドツール
プロジェクト情報: Xcode プロジェクトとワークスペースのスキームを一覧表示し、ビルド設定を表示するツール
クリーン操作: xcodebuild のネイティブクリーンアクションを使用してビルド製品をクリーンします
インクリメンタルビルドサポート: インクリメンタルビルドサポートを使用した超高速ビルド (実験的、オプトインが必要)

シミュレータ管理

シミュレータコントロール: iOSシミュレータの一覧表示、起動、開く
アプリの展開: iOSシミュレーターにアプリをインストールして起動する
ログキャプチャ:シミュレータから実行時のログをキャプチャする
UI オートメーション: シミュレーターの UI 要素を操作する (ベータ版)
スクリーンショット: シミュレータからスクリーンショットをキャプチャする (ベータ版)

アプリユーティリティ

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

はじめる

前提条件

macOS 14.5以降
Xcode 16.x以降
見世

miseを使った1行セットアップ

miseをインストールするには:

# macOS (Homebrew)
brew install mise

# Other installation methods
# See https://mise.jdx.dev/getting-started.html

mise の詳細については、公式ドキュメントをご覧ください。

MCPクライアントを構成する

クライアントアプリケーションの MCP 構成を修正し、使用するバージョンに合わせてバージョン番号を変更して、MCP クライアント (Windsurf、Cursor、Claude Desktop など) が XcodeBuildMCP サーバーを使用するように構成します。

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

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

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

VS Codeでワンクリックでインストール

UI オートメーションの有効化（ベータ版）

UI 自動化機能 (タップ、スワイプ、スクリーンショットなど) を使用するには、Facebook の idb_companion をインストールする必要があります。

brew tap facebook/fb
brew install idb-companion

idbクライアントも必要ですが、XcodeBuildMCPが自動的にインストールを試みます。それでもUI自動化機能が利用できない場合は、以下のコマンドを使用してクライアントを手動でインストールできます（Pythonがインストールされていることを前提としています）。

pipx install fb-idb==1.1.7

[!重要] UI自動化機能は現在ベータ版であるため、未完成な点がある可能性があります。問題が発生した場合は、問題追跡システムからご報告ください。

[!NOTE] ツール応答に画像を表示し、チャットコンテキストに埋め込むことは、すべての MCP クライアントでサポートされているわけではありません。現在、Cursor ではサポートされていることが分かっています。

増分ビルドのサポート

XcodeBuildMCPには、増分ビルドの試験的なサポートが含まれています。この機能はデフォルトで無効になっていますが、環境変数INCREMENTAL_BUILDS_ENABLED trueに設定することで有効にできます。

増分ビルドを有効にするには、 INCREMENTAL_BUILDS_ENABLED環境変数をtrueに設定します。

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

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "mise",
      "args": [
        "x",
        "npm:xcodebuildmcp@1.4.0",
        "--",
        "xcodebuildmcp"
      ],
      "env": {
        "INCREMENTAL_BUILDS_ENABLED": "true"
      }        
    }
  }
}

[!重要] 増分ビルドのサポートは現在試験段階であり、状況によって動作が異なる場合がありますのでご注意ください。問題が発生した場合は、問題追跡システムにご報告ください。

トラブルシューティング

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

診断ツール

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

miseと一緒に使う

# Run the diagnostic tool using mise
mise x npm:xcodebuildmcp@1.4.0 -- xcodebuildmcp-diagnostic

npx での使用

# Run the diagnostic tool using npx
npx xcodebuildmcp@1.4.0 xcodebuildmcp-diagnostic

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

システムとNode.js環境
Xcodeのインストールと設定
必要な依存関係 (xcodebuild、idb など)
XcodeBuildMCP に影響する環境変数
機能の可用性ステータス

GitHub で問題を報告する場合は、トラブルシューティングに役立つように、診断ツールからの完全な出力を含めてください。

MCP サーバーログ

MCPサーバーのログメッセージにアクセスできれば、問題を特定するのに役立ちます。ログはクライアントアプリケーションによってキャプチャされます。例えば、Cursorで取得されます。

カーソル：

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

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

プライバシー

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

Sentry には何が送信されますか?

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

Sentryからのオプトアウト

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

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

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "mise",
      "args": [
        "x",
        "npm:xcodebuildmcp@1.4.0",
        "--",
        "xcodebuildmcp"
      ],
      "env": {
        "SENTRY_DISABLED": "true"
      }        
    }
  }
}

選択ツール登録

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

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

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "mise",
      "args": [
        "x",
        "npm:xcodebuildmcp@1.4.0",
        "--",
        "xcodebuildmcp"
      ],
      "env": {
        "XCODEBUILDMCP_GROUP_IOS_SIMULATOR_WORKFLOW": "true"
      }        
    }
  }
}

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

デモ

カーソルでのビルドエラーの自動修正

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

Claude Desktop で iOS アプリを構築して実行する

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

貢献

貢献を歓迎します! XcodeBuildMCP の改善にご協力いただく方法は次のとおりです。

ローカル環境を構成してプロジェクトに貢献する方法の詳細については、 CONTRIBUTINGドキュメントを参照してください。

ライセンス

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

Integrations

目次

概要

なぜ？

特徴