xcodeproj-mcp-server

xcodeproj-mcp-server

Swift を使用して Xcode プロジェクトファイル（.xcodeproj）を操作する Model Context Protocol（MCP）サーバーです。

概要

xcodeproj-mcp-server は、Xcode プロジェクトファイルをプログラムから操作するツールを提供する MCP サーバーです。tuist/xcodeproj ライブラリを活用してプロジェクトファイルを確実に操作し、swift-sdk を使用して Model Context Protocol を実装しています。

このサーバーにより、AI アシスタントやその他の MCP クライアントは次のことを実行できます。

• 新しい Xcode プロジェクトを作成する
• ターゲット、ファイル、ビルド設定を管理する
• グループや階層を含むプロジェクト構造を調べる
• ビルド設定を変更する
• 依存関係やフレームワークを追加する
• 一般的な Xcode プロジェクトのタスクを自動化する

ユースケース

プロジェクトの作成とセットアップ

• ゼロからプロジェクトを作成する：Xcode を開かずに、カスタム設定、バンドル識別子、組織設定を指定して新しい Xcode プロジェクトを生成します
• 複数ターゲットのプロジェクトのひな形を作成する：複数のアプリ、フレームワーク、テスト、拡張機能を含む複雑なプロジェクトを、1 つの自動化されたワークフローで設定します

開発ワークフローの自動化

• ターゲットに新しいファイルを追加する：新しい Swift ファイルを作成した後、コンパイル対象となる適切なターゲットのソースファイルに自動的に追加します
• フォルダー参照を追加する：外部リソースフォルダーやアセットディレクトリを、同期フォルダー参照としてプロジェクトに追加し、ファイルシステム上の変更を自動的に反映します
• ビルドフェーズを追加する：コードフォーマッター、リンター、カスタムビルドスクリプトをターゲットに組み込みます（例：SwiftLint、SwiftFormat の実行フェーズ）
• フレームワークやアプリ拡張機能を作成する：コードベースをモジュール化するための新しいフレームワークターゲットやアプリ拡張機能をすばやく作成します
• ウィジェット拡張機能を追加する：iOS のホーム画面ウィジェット向けに、適切な設定を備えたウィジェット拡張機能ターゲットを自動的に作成して埋め込みます

プロジェクト設定の管理

• Info.plist の設定を自動化する：各ターゲットの Info.plist 設定、エンタイトルメント、プロビジョニングプロファイルをプログラムから構成します
• ビルド設定を管理する：適切なコンパイラーフラグ、バンドル識別子、デプロイメントターゲットを指定して、さまざまなビルド設定を用意します
• 依存関係を管理する：Xcode を手動で操作せずに、システムフレームワークを追加し、ライブラリをリンクして、ターゲットの依存関係を構成します

Claude Desktop と Claude Code のセットアップ方法

前提条件

• macOS（Xcode プロジェクトの実行用）
• コンテナランタイム：Apple の container（推奨）または Docker

このサーバーは linux/arm64 コンテナイメージとして配布されており、どちらのランタイムでも実行できます。

Apple の container を使ったセットアップ（推奨）

container は、macOS 上で Linux コンテナを軽量な仮想マシンとして実行するための Apple 独自のツールです。このサーバーでは推奨ランタイムです。Apple が提供しており、サードパーティ製のデスクトップアプリは不要で、公開されている linux/arm64 イメージを Apple シリコン上でネイティブに実行できます。

要件

• Apple シリコン搭載の Mac
• macOS 26 以降（container はそれ以前のバージョンをサポートしていません）

インストール

公式リリースページから container CLI をインストールします。

container を使うには、バックグラウンドサービスが実行されている必要があります。インストール後に一度起動し、再起動するたびにもう一度起動してください。

container system start

次に、GitHub Container Registry からビルド済みイメージを取得します。

container image pull ghcr.io/giginet/xcodeproj-mcp-server:latest

container run には --pull オプションがないため、最新イメージに更新する場合は、その都度 container image pull を実行してください。

Claude Code の設定

claude mcp add xcodeproj -- container run --rm -i -v '${CLAUDE_PROJECT_DIR:-.}:/workspace' ghcr.io/giginet/xcodeproj-mcp-server:latest /workspace

これにより、プロジェクトディレクトリがコンテナ内の /workspace にマウントされ、サーバーが Xcode プロジェクトにアクセスできるようになります。シングルクォートはそのままにしてください。登録時にシェルがマウントを展開するのを防ぎ、claude mcp add を実行したディレクトリに固定するのではなく、Claude Code がサーバーを起動するたびに解決されるようにします。Claude Code がサーバーを起動する作業ディレクトリであるプロジェクトルートを、. にフォールバックします。

Claude Desktop の設定

以下を Claude Desktop の設定ファイルに追加します。

macOS：~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "xcodeproj": {
      "command": "/usr/local/bin/container",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "${workspaceFolder}:/workspace",
        "ghcr.io/giginet/xcodeproj-mcp-server",
        "/workspace"
      ]
    }
  }
}

インストーラーはバイナリを /usr/local/bin/container に配置します。GUI アプリケーションでは、このディレクトリが PATH に含まれていないことがあるため、ここでは絶対パスを使用しています。

イメージをローカルでビルドする

container build は同じ Dockerfile を読み込みます。

container build -t xcodeproj-mcp-server:local .

ビルダーコンテナのデフォルト設定は 2 CPU、メモリ 2 GB です。リリースビルドを高速化するには、割り当てを増やしてください。

container build -c 8 -m 8g -t xcodeproj-mcp-server:local .

Docker を使ったセットアップ

macOS 15 以前を使用している場合、または Docker がすでにワークフローに組み込まれている場合は、Docker を使用してください。

GitHub Container Registry からビルド済みの Docker イメージを取得します。

docker pull ghcr.io/giginet/xcodeproj-mcp-server

Claude Code の設定

claude mcp add xcodeproj -- docker run --pull=always --rm -i -v '${CLAUDE_PROJECT_DIR:-.}:/workspace' ghcr.io/giginet/xcodeproj-mcp-server:latest /workspace

container の場合と同様に、プロジェクトディレクトリはコンテナ内の /workspace にマウントされるため、サーバーは Xcode プロジェクトにアクセスできます。また、シングルクォートにより、Claude Code がサーバーを起動するまでマウントは展開されません。

Claude Desktop の設定

以下を Claude Desktop の設定ファイルに追加します。

macOS：~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "xcodeproj": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "${workspaceFolder}:/workspace",
        "ghcr.io/giginet/xcodeproj-mcp-server",
        "/workspace"
      ]
    }
  }
}

Xcode 内の Claude Code または Codex からサーバーを使う

Xcode では Claude Code と Codex をコーディングエージェントとして実行でき、Xcode 専用のフォルダーである ~/Library/Developer/Xcode/CodingAssistant 内のエージェントごとのサブフォルダーから設定を読み込みます。ここに配置した設定は、Xcode で起動した場合にのみエージェントに適用されるため、通常の ~/.claude や ~/.codex の設定には影響しません。詳しくは、Apple のエージェントの拡張とカスタマイズを参照してください。

コマンドラインでのセットアップと異なる点は 2 つあります。

• Xcode はプロジェクトディレクトリを作業ディレクトリとして MCP サーバーを起動するため、. を直接マウントします。Codex には Claude Code の ${CLAUDE_PROJECT_DIR:-.} に相当する展開機能がないため、両方のエージェントで同じマウントを使用できます。
• エージェントの環境では /usr/local/bin が PATH に含まれているとは限らないため、command には絶対パスを指定します。

Xcode 内の Claude Code

~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig は Claude Code の設定ディレクトリとして機能します。CLAUDE_CONFIG_DIR をこのディレクトリに設定し、claude mcp add を使用します。

CLAUDE_CONFIG_DIR=~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig \
  claude mcp add xcodeproj -s user -- \
  /usr/local/bin/container run --rm -i -v .:/workspace ghcr.io/giginet/xcodeproj-mcp-server:latest /workspace

これにより、サーバーが ClaudeAgentConfig/.claude.json に書き込まれます。代わりに手動で追加する場合は、mcpServers の下にエントリを追加します。

{
  "mcpServers": {
    "xcodeproj": {
      "type": "stdio",
      "command": "/usr/local/bin/container",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        ".:/workspace",
        "ghcr.io/giginet/xcodeproj-mcp-server:latest",
        "/workspace"
      ]
    }
  }
}

Xcode の Codex

~/Library/Developer/Xcode/CodingAssistant/codex は、Codex の CODEX_HOME として機能します：

CODEX_HOME=~/Library/Developer/Xcode/CodingAssistant/codex \
  codex mcp add xcodeproj -- \
  /usr/local/bin/container run --rm -i -v .:/workspace ghcr.io/giginet/xcodeproj-mcp-server:latest /workspace

これにより、サーバーが codex/config.toml に書き込まれます。手動で追加する場合：

[mcp_servers.xcodeproj]
command = "/usr/local/bin/container"
args = ["run", "--rm", "-i", "-v", ".:/workspace", "ghcr.io/giginet/xcodeproj-mcp-server:latest", "/workspace"]

Docker でセットアップする場合は、/usr/local/bin/container の代わりに docker バイナリの絶対パスを使用してください。設定を変更した後は、Xcode でエージェントを再起動してください。

Claude Code の推奨設定

.claude/settings.json で ENABLE_TOOL_SEARCH を有効にすると、MCP ツールの動的な読み込みが有効になります。これにより、使用していない MCP ツールがコンテキストを消費するのを防げます。

{
  "env": {
    "ENABLE_TOOL_SEARCH": "1"
  }
}

パスのセキュリティ

MCP サーバーでは、ファイル操作を特定のベースディレクトリに制限できるようになりました。コマンドライン引数としてベースパスを指定すると：

• すべての project_path とファイルパスのパラメーターが、このベースパスを基準として解決されます
• 絶対パスがベースディレクトリ内にあることを検証します
• ベースディレクトリ外のファイルにアクセスしようとすると、エラーになります

これは、サーバーをコンテナーやその他のサンドボックス環境で実行する場合に特に便利です。

利用可能なツール

プロジェクト管理

• create_xcodeproj - 新しい Xcode プロジェクトを作成します

  • パラメーター：project_name、path、organization_name、bundle_identifier

• list_targets - プロジェクト内のすべてのターゲットを一覧表示します

  • パラメーター：project_path

• list_build_configurations - すべてのビルド設定を一覧表示します

  • パラメーター：project_path

• list_files - 特定のターゲット内のすべてのファイルを一覧表示します

  • パラメーター：project_path、target_name

• list_groups - プロジェクト内のすべてのグループを階層パス付きで一覧表示します。ターゲットで絞り込むこともできます

  • パラメーター：project_path、target_name（任意）

ファイル操作

• add_file - ファイルをプロジェクトに追加します

  • パラメーター：project_path、file_path、target_name、group_path

• remove_file - ファイルをプロジェクトから削除します

  • パラメーター：project_path、file_path

• move_file - プロジェクト内でファイルを移動または名前変更します

  • パラメーター：project_path、source_path、destination_path

• add_synchronized_folder - 同期フォルダーの参照をプロジェクトに追加します

  • パラメーター：project_path、folder_path、group_name、target_name

• create_group - プロジェクトナビゲーターに新しいグループを作成します

  • パラメーター：project_path、group_name、parent_group_path

ターゲット管理

• add_target - 新しいターゲットを作成します

  • パラメーター：project_path、target_name、type、platform、bundle_identifier

• remove_target - 既存のターゲットを削除します

  • パラメーター：project_path、target_name

• duplicate_target - 既存のターゲットを複製します

  • パラメーター：project_path、source_target_name、new_target_name

• add_dependency - ターゲット間の依存関係を追加します

  • パラメーター：project_path、target_name、dependency_name

アプリ拡張機能の管理

• add_app_extension - App Extension ターゲットを追加し、ホストアプリに埋め込みます

  • パラメーター：project_path、extension_name、extension_type、host_target_name、bundle_identifier、platform（任意）、deployment_target（任意）
  • 対応する拡張機能の種類：widget、notification_service、notification_content、share、today、action、file_provider、intents、intents_ui、keyboard、photo_editing、document_provider、custom

• remove_app_extension - App Extension ターゲットと、ホストアプリへの埋め込みを削除します

  • パラメーター：project_path、extension_name

ビルド設定

• get_build_settings - ターゲットのビルド設定を取得します

  • パラメーター：project_path、target_name、configuration_name

• set_build_setting - ビルド設定を変更します

  • パラメーター：project_path、target_name、setting_name、value、configuration_name

• add_framework - フレームワークの依存関係を追加します

  • パラメーター：project_path、target_name、framework_name、embed

• add_build_phase - カスタムビルドフェーズを追加します

  • パラメーター：project_path、target_name、phase_type、name、script

Swift パッケージ管理

• add_swift_package - Swift パッケージの依存関係をプロジェクトに追加します

  • パラメーター：project_path、package_url、requirement、target_name、product_name

• list_swift_packages - プロジェクト内のすべての Swift パッケージの依存関係を一覧表示します

  • パラメーター：project_path

• remove_swift_package - プロジェクトから Swift パッケージの依存関係を削除します

  • パラメーター：project_path、package_url、remove_from_targets

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。