xcforge - iOS MCP Server & CLI

xcforge

iOS 開発向けの MCP サーバーおよび CLI です。あらゆる AI エージェントやターミナルから、ビルド、テスト、自動化、診断を実行できます。

MCP ツール 104 個。CLI コマンドグループ 19 個。単一のネイティブバイナリ（ストリップ後約 8 MB、デバッグシンボル込みで約 18 MB）。外部ランタイム依存関係はありません。

---

インストール

Homebrew（推奨）

brew tap justinthevoid/tap && brew install xcforge

Claude Code（ワンライナー）

claude mcp add xcforge -- xcforge

これにより、現在のプロジェクトで xcforge が MCP サーバーとして登録されます。Homebrew でインストールした後に実行してください。

ソースから

git clone https://github.com/justinthevoid/xcforge.git
cd xcforge && swift build -c release
cp .build/release/XCForgeCLI /usr/local/bin/xcforge

アンインストール

Homebrew

brew uninstall xcforge
brew untap justinthevoid/tap   # optional: remove the tap

ソースから

rm /usr/local/bin/xcforge

MCP 設定を削除する

バイナリをアンインストールした後、MCP クライアントの設定ファイルから "xcforge" エントリを削除してください（ファイルの場所については［設定］(#configure)を参照）。

Claude Code の場合：

claude mcp remove xcforge

---

設定

xcforge を MCP クライアントに追加します。クライアントごとに設定形式とファイルの場所が異なります。

Claude Code

最も簡単な方法は、上記の［インストール］(#install)に記載されている CLI コマンドを使うことです。手動で設定する場合は、プロジェクトのルートにある .mcp.json（グローバル設定の場合は ~/.claude/.mcp.json）に追加します。

{
  "mcpServers": {
    "xcforge": {
      "command": "xcforge",
      "args": [],
      "type": "stdio"
    }
  }
}

Claude Desktop

ファイル：~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "xcforge": {
      "command": "/opt/homebrew/bin/xcforge",
      "args": []
    }
  }
}

注： Claude Desktop はシェルの PATH を引き継ぎません。Homebrew の絶対パスを使用してください。Apple Silicon では /opt/homebrew/bin/xcforge、Intel では /usr/local/bin/xcforge です。

Cursor

ファイル：プロジェクトのルートにある .cursor/mcp.json（グローバル設定の場合は ~/.cursor/mcp.json）

{
  "mcpServers": {
    "xcforge": {
      "command": "/opt/homebrew/bin/xcforge",
      "args": []
    }
  }
}

注： PATH に関する注意点は Claude Desktop と同じです。絶対パスを使用してください。変更後は Cursor を再起動してください。

VS Code（GitHub Copilot）

ファイル：プロジェクトのルートにある .vscode/mcp.json

{
  "servers": {
    "xcforge": {
      "command": "xcforge",
      "args": [],
      "type": "stdio"
    }
  }
}

注： VS Code では "mcpServers" ではなく "servers" を使用します。エージェントモードを有効にした GitHub Copilot 拡張機能が必要です。VS Code は通常、シェルから PATH を解決するため、コマンド名だけで動作します。

Windsurf

ファイル：~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "xcforge": {
      "command": "/opt/homebrew/bin/xcforge",
      "args": []
    }
  }
}

注： 絶対パスの使用を推奨します。編集後は Windsurf を再起動してください。

Zed

ファイル：~/.config/zed/settings.json（またはプロジェクトごとの .zed/settings.json）

{
  "context_servers": {
    "xcforge": {
      "command": {
        "path": "/opt/homebrew/bin/xcforge",
        "args": []
      },
      "settings": {}
    }
  }
}

注： Zed では "context_servers" と、入れ子になった "command.path" を使用します。他のすべてのクライアントとは異なる形式です。

設定のクイックリファレンス

クライアント	設定キー	ファイルの場所	絶対パスが必要ですか？
Claude Code	mcpServers	.mcp.json	いいえ
Claude Desktop	mcpServers	~/Library/Application Support/Claude/claude_desktop_config.json	はい
Cursor	mcpServers	.cursor/mcp.json	はい
VS Code	servers	.vscode/mcp.json	いいえ
Windsurf	mcpServers	~/.codeium/windsurf/mcp_config.json	はい
Zed	context_servers	~/.config/zed/settings.json	はい

---

Claude Code スキル

xcforge にはエージェントスキルが同梱されています。これは、エージェントが iOS タスクに取り組む際に読み込むツールリファレンスです。バイナリに含まれているため、インストールにほかのものは必要ありません。

xcforge skill install            # this repo: .claude/skills/xcforge (commit it to share with the team)
xcforge skill install --global   # every project: ~/.claude/skills/xcforge
xcforge skill install --dir <skills-dir>      # any other agent's skills directory
xcforge skill status             # where it's installed and whether it matches this xcforge
xcforge skill show references/test-tools.md   # print one file without installing

xcforge をアップグレードした後に xcforge skill install を再実行すると、コピーが更新されます。変更されたファイルのみが書き換えられます。--force を指定しない限り、xcforge が作成したものではない xcforge スキルディレクトリは上書きされません。xcforge skill uninstall で削除できます。

インストールすると、xcforge ツールを使用する際に Claude が適切なリファレンスファイルを自動的に読み込みます。各カテゴリ（ビルド、テスト、シミュレーター、UI 自動化、ログ、LLDB、診断など）の正確なパラメーター、戻り値、使用パターンが記載されています。

---

2 つのモード、同じツール

xcforge                          # MCP server (stdio JSON-RPC, 104 tools)
xcforge build --scheme MyApp     # CLI mode (19 command groups)

MCP 経由で利用できるすべてのツールには、対応する CLI コマンドがあります。すべての CLI コマンドで --json を使用できます。

---

ツールの概要

カテゴリ	数	主な機能
ビルド	6	build_sim、build_compile（コンパイルのみの高速ビルド）、build_run_sim、clean、プロジェクト／スキームの検出
テスト	7	xcresult の解析に対応した test_sim、test_failures、test_coverage、list_tests、test_plan_inspect、エージェント出力モード、既知の失敗を考慮したゲーティング
シミュレーター	18	ライフサイクル全般とビデオ録画、位置情報のシミュレーション、ダークモードの切り替え、ステータスバーのオーバーライド、情報
実機	10	devicectl 経由 — 一覧表示、インストール、起動（ディープリンク、環境変数）、スクリーンショット、デバイス上の WebDriverAgent
UI 自動化	20	WebDriverAgent とネイティブ AX ブリッジ — 検索、タップ（座標またはピクセル）、スワイプ、ドラッグ、入力、アラート
スクリーンショット	3	フレームバッファーのキャプチャ（0.3 秒）、ポイント単位の座標との整合、グリッドのオーバーレイ（オプション）
ビジュアルリグレッション	3	ピクセル差分のベースライン、複数デバイスでのチェック（ダークモード、横向き、iPad）、bless ワークフロー
ログ	4	4 層のフィルターによるキャプチャ、8 つのトピックカテゴリ、正規表現による待機
コンソール	3	起動したアプリの stdout／stderr のキャプチャ
SPM	5	依存関係の解決、更新、依存関係の表示、リセット、クリーン
アクセシビリティ	5	ラベル、特性、VoiceOver の読み上げ順序、コントラストの監査
Git	5	ステータス、差分、ログ、コミット、ブランチ
LLDB デバッガー	8	アタッチ、ブレークポイント、変数の検査、バックトレース、ステップ実行／続行、任意のコマンド
診断	10	複数ステップのワークフロー：ビルド、実行、検査、証拠のキャプチャ、比較、検証
プラン実行	2	アサーションを含むスクリプト化された複数ステップの自動化
セッション	3	永続的なデフォルト設定、.xcforge.yaml リポジトリ設定、セッションプロファイル

---

主な機能

構造化されたテスト結果

テスト出力は、Xcode が内部で生成する構造化形式である .xcresult バンドルから解析されます。生の xcodebuild stdout／stderr から解析するのではありません。

1 回の test_sim 呼び出しで、成功／失敗の件数、ソース位置を含む失敗メッセージ、エクスポートされた失敗時のスクリーンショット、さらに test_failures または test_coverage で詳しく調べるための xcresult パスが返されます。

高速なスクリーンショット

​screenshot ツールは、CoreSimulator の IOSurface API を使用してシミュレーターのフレームバッファーを読み取り、利用できない場合は ScreenCaptureKit、次に simctl にフォールバックします。一般的なレイテンシは約 300ms です。

Appium を使わない UI 自動化

xcforge は HTTP 経由で WebDriverAgent と直接通信し、ネイティブ Accessibility API ブリッジ（AXPBridge）で機能を補います。これにより、次のことが可能です。

• find_element は scroll: true を指定すると、3 つのフォールバック戦略を使用して自動スクロールします
• handle_alert は SpringBoard、ContactsUI、アクティブなアプリを対象に検索します — accept_all を使うと、複数の権限ダイアログを 1 回の呼び出しで閉じられます
• drag_and_drop は座標だけでなく、要素 ID でも動作します
• get_source は完全なビュー階層を約 20ms で返します

トピックでフィルタリングしたログ

start_log_capture は、4 層のフィルターを通して os_log をストリーミングします。

1. ノイズの除外 — ストリームレベルで、既知のノイズの多い 15 個のプロセスを除外します
2. キャプチャモード — smart（広範囲でトピックに対応）、app（自動検出したバンドルに絞り込み）、verbose
3. トピックフィルタリング — read_logs がログ行を 8 つのトピック（app、crashes、network、lifecycle、springboard、widgets、background、system）に分類し、デフォルトでは app と crashes のみを表示します
4. 重複排除 — 繰り返されるログ行をまとめます

レスポンスには件数付きのトピックメニューが含まれるため、エージェントは再クエリせずに必要なトピックを指定して取得できます。

インタラクティブ LLDB デバッガー

実行中のシミュレーターのプロセスへの LLDB のアタッチ、ブレークポイントの設定、変数の調査、スタックトレースの表示、コードのステップ実行に対応する 8 つのツールです。セッションは 30 分間維持されるため、一度アタッチすれば複数のデバッグ操作を実行できます。CLI コマンドは 1 回限りで、アタッチ → 操作 → デタッチの順に実行されます。次の機能が含まれます。

• セッション管理：lldb_attach（バンドル ID または PID を指定）、lldb_detach
• ブレークポイント：ファイルと行番号、または関数名を指定して設定し、ID で削除します
• 調査：現在のフレームで式を評価し、スタックトレースを表示します
• 実行制御：続行、ステップオーバー、ステップイン、ステップアウト（タイムアウトは 10 秒）
• 生コマンドのパススルー：任意の LLDB コマンドを実行します

ログやスクリーンショットと併用することで、根本原因を体系的に分析できます。

診断ワークフロー

10 個のツール（デフォルトでは無効です。XCFORGE_TOOL_GROUPS=+diagnose または tool_groups で有効にします）が連携し、構造化された診断パイプラインを構成します。セッションの開始、ビルド、起動、ランタイムシグナルのキャプチャ、証拠（スクリーンショット、ログ、アクセシビリティの状態）の収集、前回の実行との比較、修正の検証を行います。エージェントが複数回の反復を通じて問題を体系的にデバッグできるよう設計されています。

物理デバイスのサポート

実機向けの Apple の devicectl をラップするツールです。接続済みデバイスの一覧表示、アプリのインストール、起動（ディープリンクと環境変数に対応）、終了、スクリーンショットの撮影を行えます。xcforge wda start --device <udid> --team <TEAM>（MCP の wda_start）は、デバイス上で WebDriverAgent をビルド、署名、起動し、UI 自動化ツールを使用できるようにします。詳細は device-tools.md を参照してください。

---

CLI の使用例

xcforge init                                     # Scaffold a committed .xcforge.yaml (repo defaults)
xcforge build                                    # Build (auto-detects project, scheme, sim)
xcforge build compile --scheme MyApp             # Fast compile-only check (~5s)
xcforge build --scheme MyApp --simulator "iPhone 16 Pro"
xcforge test --scheme MyApp --json               # Run tests, JSON output
xcforge test --for agent                         # Agent-optimized slim JSON
xcforge test --gate                              # Subtract known-failures.yaml
xcforge test rerun-failed                        # Replay last run's failures
xcforge test plan inspect --plan AllTests        # Inspect .xctestplan
xcforge build-test --env BLESS_BASELINE=1        # Inject env var into test process
xcforge test failures --xcresult /path/to.xcresult
xcforge test coverage --min-coverage 80
xcforge bless --baseline login --tests "UITests/LoginTests"  # Baseline+test+diff in one call
xcforge sim list                                 # List simulators
xcforge sim boot "iPhone 16 Pro"
xcforge sim info                                 # Booted simulator screen size and scale
xcforge ui find --aid "loginButton"              # Find by accessibility ID
xcforge ui tap --element el-0                    # Tap element at point coordinates
xcforge ui tap-pixel --x 750 --y 1334            # Tap at pixel coordinates
xcforge screenshot                               # Screenshot to stdout
xcforge screenshot --grid --output /tmp/x.png    # Screenshot with point-coordinate grid
xcforge pose Settings                            # Build, install, launch to a screen
xcforge log start                                # Start log capture
xcforge log read --include network               # Read with topic filter
xcforge spm resolve                              # Resolve packages
xcforge device list                              # Connected physical devices
xcforge debug attach --bundle-id com.example.App    # Attach debugger
xcforge debug breakpoint set --bundle-id com.example.App --file ViewController.swift --line 42
xcforge debug inspect --bundle-id com.example.App --expression "self.count"
xcforge debug backtrace --bundle-id com.example.App # Show stack trace
xcforge debug continue --bundle-id com.example.App --mode step-over
xcforge diagnose start --scheme MyApp            # Start diagnosis session

---

代替ツール

iOS に特化した MCP サーバーには、知っておく価値のあるものがいくつかあります。

サーバー	Stars	範囲	ビルド	テスト	UI 自動化	スクリーンショット	ビジュアルリグレッション	アクセシビリティ	実機	SPM	Git	ログ
xcforge	—	104 ツール	はい	はい	はい	はい	はい	はい	はい	はい	はい	はい
XcodeBuildMCP	~5k	~15 ツール	はい	はい	一部	いいえ	いいえ	いいえ	いいえ	いいえ	いいえ	いいえ
ios-simulator-mcp	~1.8k	~10 ツール	いいえ	いいえ	はい	はい	いいえ	いいえ	いいえ	いいえ	いいえ	いいえ
xcode-mcp-server	~370	~8 ツール	一部	いいえ	いいえ	いいえ	いいえ	いいえ	いいえ	いいえ	いいえ	いいえ
iosef	<10	~5 ツール	いいえ	いいえ	はい	いいえ	いいえ	いいえ	いいえ	いいえ	いいえ	いいえ
Appium MCP	<50	~10 ツール	いいえ	いいえ	はい	はい	いいえ	いいえ	一部	いいえ	いいえ	いいえ

• XcodeBuildMCP — 最も人気のある iOS 向け MCP サーバーです。Sentry が支援しています。ビルド、テスト、シミュレーター管理に優れています。ビルド／実行のワークフローだけが必要なら、堅実な選択肢です。
• ios-simulator-mcp — シミュレーターの UI 操作に特化しており、スクリーンショット、タップ、スワイプ、アクセシビリティツリーに対応しています。シミュレーターの自動化だけが必要な場合に適しています。
• xcode-mcp-server — Xcode プロジェクト管理向けの初期の MCP サーバーです。基本的な連携に限られ、シミュレーターの自動化、テスト、デバイスには対応していません。
• iosef — エージェント向けに最適化された、使いやすいシミュレーター CLI です。範囲は限られていますが、設計には工夫が凝らされています。Swift ネイティブです。
• Appium MCP — Appium エコシステムを通じて iOS と Android の両方に対応します。Node.js、Java、Appium サーバーが必要で、依存関係が多くなります。

xcforge の位置づけ： 高速なコンパイルチェック、ビルド、テスト、ピクセル単位で正確な UI 自動化、スクリーンショットのグリッド表示、画面を指定した起動、ログ分析、ビジュアルリグレッション、デバイス対応、SPM、アクセシビリティ監査、複数ステップの診断を、依存関係ゼロの単一バイナリに統合しています。一方で、iOS 専用であり、Android、watchOS、visionOS には対応していません。

---

UI 自動化のセットアップ

UI 自動化ツールを使うには、シミュレーター上で WebDriverAgent（WDA）のバックエンドが実行されている必要があります。xcforge は WDA への接続を自動的に管理するため、WDA プロジェクトを指定するだけで使えます。

xcforge は、次の順序で 2 つのバックエンドを試します。

1. xcforgeWDA（優先） — xcforge 独自の WDA フォーク（com.xcforge.wda.runner）です。XCFORGE_WDA_DIR を設定すると、自動的にビルドされ、デプロイされます。
2. オリジナルの WebDriverAgent（フォールバック） — Facebook/Appium の WDA です。WDA がすでにポート 8100 で実行されていれば、自動的に検出されます。

クイックセットアップ

appium/WebDriverAgent をクローンし、xcforge 用にプロジェクト名とスキーム名を変更してから、XCFORGE_WDA_DIR を設定します。

git clone https://github.com/appium/WebDriverAgent.git xcforgeWDA

# Copy project with xcforge name and remap bundle ID
cp -r xcforgeWDA/WebDriverAgent.xcodeproj xcforgeWDA/xcforgeWDA.xcodeproj
sed -i '' 's/com\.facebook\.WebDriverAgentRunner/com.xcforge.wda.runner/g' \
  xcforgeWDA/xcforgeWDA.xcodeproj/project.pbxproj

# Add xcforgeWDARunner scheme
cp xcforgeWDA/xcforgeWDA.xcodeproj/xcshareddata/xcschemes/WebDriverAgentRunner.xcscheme \
   xcforgeWDA/xcforgeWDA.xcodeproj/xcshareddata/xcschemes/xcforgeWDARunner.xcscheme
sed -i '' 's/WebDriverAgent\.xcodeproj/xcforgeWDA.xcodeproj/g' \
  xcforgeWDA/xcforgeWDA.xcodeproj/xcshareddata/xcschemes/xcforgeWDARunner.xcscheme

次に、MCP の設定に XCFORGE_WDA_DIR を追加します。

{
  "mcpServers": {
    "xcforge": {
      "command": "xcforge",
      "env": {
        "XCFORGE_WDA_DIR": "/path/to/xcforgeWDA"
      }
    }
  }
}

xcforge は、シミュレーターで最初に UI ツールを呼び出したときに WDA を自動でビルドしてデプロイします（初回は約30～60秒かかりますが、以降はすぐに完了します）。実機の場合は、デバイスのロックを解除し、「設定」>「デベロッパ」>「UI Automation を有効にする」をオンにした状態で、最初に xcforge wda start --device <udid> --team <TEAM>（MCP wda_start）を実行します。別の設定、カスタムポート、トラブルシューティングについては、UI Automation セットアップガイド全文をご覧ください。

---

要件

• macOS 13+
• Xcode 15+
• Swift 6.0+（ソースからビルドする場合のみ）
• WebDriverAgent（UI オートメーションのみ — UI Automation Setupを参照）

---

Web の基本構成（ストーリー 1.1）

Web ワークスペースは Web/ 配下に分離されており、Astro Starlight と Svelte を使用します。パッケージとスクリプトの実行には Bun のみを使用し、リントとフォーマットのチェックには Biome のみを使用します。

cd Web
bun install
bun run typecheck
bun run lint
bun run validate

bun run dev 実行後のローカルルートは次のとおりです。

• マーケティングルート：http://localhost:4321/
• ドキュメントルート：http://localhost:4321/docs
• ドキュメントの下層ルート：http://localhost:4321/docs/getting-started

セットアップに失敗した場合は、次を実行してください。

cd Web
bun run doctor

問題の解決手順は Web/README.md に記載されています。

---

サポート

xcforge によって時間を節約できた場合は、開発へのご支援をご検討ください。

ライセンス

MIT — LICENSEを参照してください。

コントリビューション

Issue と PR を歓迎します。CONTRIBUTING.mdをご覧ください。