Claude CodeのXcodeプラグイン:導入・接続とMCPエラーの対処
AppleのプラグインまたはMCPサーバーの手動登録で、Claude CodeをXcodeに接続します。ローカルのエクスポートコマンドと選択中のXcodeを確認し、外部エージェントを許可して実際のビルドで接続を検証します。ツールが見つからない場合の対処とCodexの接続も、設定の適用範囲やモデルの課金と分けて説明します。
目次

Claude CodeでSwiftファイルを編集できても、Xcodeのビルド、テスト、プレビューにはアクセスできないことがあります。MacでClaude Codeを接続する前に、Xcodeで外部エージェントのアクセスを許可し、プロジェクトを開いてください。ローカルのエクスポートコマンドが動作する場合はxcode@claude-plugins-officialをインストールし、動作しない場合はAppleが案内するxcrun mcpbridgeで接続します。
以下は2026-11-16時点で公開されている公式ドキュメントに沿った手順です。権限の設定とMCPへの直接接続については、Appleの外部エージェント向けガイドに説明があります。
インストール前にMacで選択されているXcodeを確認する
コマンドラインツールだけでなくXcodeアプリ本体をインストールし、Claude Code CLI(コマンドラインから操作するクライアント)は現行版を使います。マーケットプレイスの登録情報は、Mac上のXcodeツールからプラグインを取得します。マーケットプレイスのパッケージをインストールしても、未導入のXcodeまでインストールされるわけではありません。
Bashでアプリのリポジトリに移動し、CLIのバージョンと選択中の開発用ディレクトリを確認します。
claude --version
xcode-select --print-path
開発用ディレクトリは、使用したいXcodeのインストール先に属している必要があります。/Library/Developer/CommandLineToolsと表示される場合、選択されているのは単体のコマンドラインツールパッケージであり、Xcodeアプリではありません。この違いはAppleのコマンドラインツール設定ガイドで確認できます。
続いて、マーケットプレイスが使うコマンドをそのまま実行します。
xcrun agent plugin path --plugin-format claude
正常に終了すると、プラグインのディレクトリを指す絶対パスが表示されます。そのディレクトリは移動や削除をせず、そのまま残してください。マーケットプレイスはmode: "link"を使い、生成されたファイルを元の場所から読み込みます。
公式の変更履歴によると、Claude Codeは2.1.229でコマンドを使うプラグインソースに対応しました。その古いバージョンに固定せず、現行版を使ってください。Xcodeについては、エクスポートコマンドが正常に動作することを確認します。mcpbridgeがあるだけで、agent plugin pathも使えるとは判断できません。
claudeコマンド自体が見つからない場合は、Xcodeを調べる前にClaude Codeのインストールと初回起動の確認を済ませてください。
外部エージェントを許可してプロジェクトを開く
XcodeのIntelligence設定で、外部プロセスからのアクセスを許可します。この権限の設定は、Claude Codeプラグインのインストールとは別の手順です。MCPはModel Context Protocolの略で、エージェントからXcodeのツールを呼び出すために使います。
- Xcode > Settings > Intelligenceを開きます。
- Model Context ProtocolのAllow External Agents to Use Xcode Toolsで、While Xcode is OpenまたはAlwaysを選びます。
- エージェントに使わせるプロジェクトまたはワークスペースを開きます。
今回のように対話的に作業する場合は、While Xcode is Openを選びます。この後の確認中は、プロジェクトを開いたままにしてください。Appleの説明では、外部エージェントが接続したときと動作中に、Xcodeが通知します。
モデルへの接続も、すでに動作している設定を維持してください。対象のClaudeサブスクリプションではプランの利用枠を消費し、Claude ConsoleのアカウントではAPI利用分が別途請求されます。既存の利用枠で足りる場合はサブスクリプション、従量課金で使いたい場合はAPIを選びます。支払い前にClaude Codeの認証方法とAnthropicの対応地域を確認してください。
BetterTokenも従量課金でAPIを使う選択肢です。自分のアカウントとコンソールで作成したキーを使い、Claude Code向けの設定手順に従って接続します。API用の残高を別に用意して使う場合に選びます。モデルの課金単位、支払い方法、手数料は支払い前に確認してください。Claudeのサブスクリプションは含まれません。現在のモデル料金を確認するとともに、支払い条件はコンソールで確認します。
プラグインとMCPへの直接接続を選び分ける
Xcodeのエクスポートコマンドが動作する場合は、プラグインを使います。ブリッジへの接続だけが必要な場合や、エクスポートコマンドが使えなくてもmcpbridgeは動作する場合は、MCPを直接登録します。
公式マーケットプレイスの登録情報では、作者はApple Inc.とされています。プラグインのソースはxcrun agent plugin path --plugin-format claudeをローカルで実行します。一方、直接接続のコマンドはxcrun mcpbridgeをMCPサーバーとして登録します。
これはパッケージの提供方法の違いであり、どちらかのビルド結果が優れているという根拠ではありません。プラグインにはMCP設定のほか、スキル(エージェントに作業手順などを伝える指示)や別の構成要素が含まれる場合があります。スキルの一覧が固定だと考えたり、両方の機能が完全に同じだと考えたりせず、インストールしたパッケージを確認してください。問題を切り分けやすくするため、最初はどちらか一方で接続します。
xcode@claude-plugins-officialをインストールする
リポジトリからclaudeでClaude Codeを起動します。次のコマンドはBashではなく、Claude Codeの対話プロンプトに入力します。
/plugin install xcode@claude-plugins-official
インストール内容を確認し、初回は、このリポジトリ内で自分だけが使うローカルスコープを選び、ほかのリポジトリと分けて試します。表示されたエクスポートコマンドが前述のコマンドと一致することを確かめてから、実行を許可してください。インストール結果に再読み込みの指示があれば従い、またはClaude Codeの新しいセッションを開始します。
次に、同じリポジトリでBashからインストール状態を確認します。
claude plugin list
claude plugin details xcode@claude-plugins-official
パッケージが有効になっていることを確認し、構成要素の一覧を調べます。プラグインのコマンドリファレンスには、スキルやMCPサーバーを含む一覧の説明があります。
Claude Codeで/mcpを実行し、プラグインが提供するサーバーを確認します。プラグインのMCPサーバーはplugin:<plugin>:<server>形式の名前を使います。単独のxcodeという名前が表示される必要はありません。
後で適用範囲を変えたり削除したりする場合は、プラグインのインストール・確認・削除ガイドを参照してください。
xcrun mcpbridgeを直接登録する
Claude Codeを使うリポジトリから、BashでAppleの登録コマンドをそのまま実行します。
claude mcp add --transport stdio xcode -- xcrun mcpbridge
claude mcp list
claude
これで標準入力と標準出力を使うローカルプロセスへの接続を登録します。このコマンドで指定したサーバー名はxcodeです。対話セッションで/mcpを実行し、接続状態を確認してからビルドを依頼してください。
MCPの既定の適用範囲は、現在のプロジェクト内です。Claude Codeは設定をプロジェクトに関連付けて~/.claude.jsonに保存し、すべてのリポジトリに自動で適用するわけではありません。詳しくはMCPの適用範囲に関するドキュメントを参照してください。
登録しただけでは、接続が機能していると確認できません。サーバーが接続し、Xcodeで開いているプロジェクトを操作できることまで確かめます。
アプリの変更を頼む前にビルドを確認する
最初はファイルを編集せずにビルドするよう依頼します。これで、接続の問題とモデルが加えた変更による問題を分けて確認できます。
接続済みのClaude Codeセッションで、次のプロンプトを使います。
Use Xcode tools to identify the open project and active scheme.
Build that scheme for an available iOS Simulator destination.
Do not edit files.
Report the build result and the first actionable error, if any.
実際にXcodeのツールが呼び出され、そのビルド結果が返っていることを確認します。Xcode側にも外部エージェントの動作が表示されるはずです。コンパイラーエラーが返る場合も、接続自体は機能していると確認できることがあります。アプリがまだビルドできなくても、プラグインを入れ直すのではなく、そのプロジェクトのエラーを修正します。
マーケットプレイスの説明には、スキームのビルド・実行・テスト、SwiftUIプレビューの描画、シミュレーターとデバイスの操作、ビルドログと診断情報の取得、Appleドキュメントの検索が挙げられています。実際に使える操作は、インストール済みのXcodeと接続されたツール一覧で確認してください。
たとえば、AppleのXcode 27リリースノートには、シミュレーターの起動、アプリのインストールと起動、タッチ入力、スクリーンショットの取得が記載されています。画面を操作するタスクを頼む前に、対応するツールが利用可能か確認します。
ビルドを確認したら、利用できるテストを調べ、関連するテストまたはテスト群を実行するようエージェントに依頼します。ビューを変更する場合は、既存のSwiftUIプレビューを描画させ、返されたプレビューを確認してください。テスト結果やプレビューそのものを確かめ、成功したという説明だけで判断しないでください。
最初のタスクは範囲を絞ります。ビルドの繰り返しや大量の診断出力を加える前に、MCPのコンテキストコストを確認する手順で、再現可能な同じタスクを比較します。
全体を入れ直すのではなく、問題のある箇所を直す
結果に合う項目を選んで確認してください。以下は状況別の対処法であり、全員が順番に実行する手順ではありません。
xcrunでagentまたはmcpbridgeが見つからない
最初にxcode-select --print-pathを確認します。古いXcodeや単体のコマンドラインツールパッケージが選ばれていると、ターミナルと開いているXcodeで異なるツールが使われることがあります。
使いたいアプリが/Applications/Xcode.appにある場合は、Bashで次のように選択します。
sudo xcode-select --switch /Applications/Xcode.app
別の場所にインストールしている場合は、実際のパスを指定します。この操作は既定の開発用ディレクトリを変更するため、切り替え後の選択を確認し、失敗したコマンドを再実行してください。
agent plugin pathが引き続き使えなくても、MCPへの直接接続が動作する場合は、その接続を使います。どちらも動作しない場合は、必要なツールを備えたXcodeをインストールするか選択してください。Claude Codeで使うモデルの認証情報を変更する前に、Xcode側で必要なツールが使える状態を整えます。
claude mcp listに単独のxcodeという項目がない
直接接続の場合は、サーバーを追加したリポジトリからコマンドを実行します。プロジェクト単位の登録は、別のリポジトリには自動で表示されません。
プラグインの場合はclaude plugin listを確認し、続いてClaude Code内で/mcpを確認します。単独のxcodeではなく、プラグイン名を含むサーバーを探してください。インストール済みでも無効になっている場合は、/pluginで有効にして、新しいセッションを開始します。
インストーラーがマーケットプレイスの登録を見つけられない場合は、Claude Codeのプロンプトでカタログを更新します。
/plugin marketplace update claude-plugins-official
更新後にインストールを再試行します。マーケットプレイス自体が未登録なら、先に/plugin marketplace add anthropics/claude-plugins-officialを実行してください。Anthropicのプラグインのトラブルシューティングでは、こうしたカタログの問題と未対応のソース形式を分けて説明しています。
サーバーは接続するがプロジェクトを使えない
目的のプロジェクトをXcodeで開き、Allow External Agents to Use Xcode Toolsを再確認します。Xcodeを開いたまま、エージェントの新しいセッションを開始し、ファイルを編集しないビルドの依頼を繰り返してください。
サーバーの項目があることは、設定が存在する証拠です。目的のプロジェクトに到達したことは、返されたプロジェクト情報とビルド結果で確認します。ツールがプロジェクト固有のエラーを返した場合は、その診断に沿って次の対処を進めてください。
同じXcodeプロジェクトにCodexを接続する
Codexでは、Claude Codeのマーケットプレイスプラグインをインストールせずに、Appleが案内するMCPへの直接接続を使えます。Xcodeの権限設定を維持し、プロジェクトを開いたままにします。
Codex CLIをインストールして認証を済ませたら、Bashで次のコマンドを実行します。
codex mcp add xcode -- xcrun mcpbridge
codex mcp list
codex
Codex内では、OpenAIのMCPドキュメントに従って/mcpで有効なサーバーを確認します。その後、同じ「ファイルを編集せずにビルドする」プロンプトを送り、返された結果を確認してください。
後で外部エージェントのアクセスを取り消す場合は、XcodeのIntelligence設定に戻り、Allow External Agents to Use Xcode ToolsでNeverを選びます。