axiom-xcode-mcp-setup

Xcode MCP のセットアップ

前提条件

• MCP に対応した Xcode 26.3+
• Xcode がインストールされ、起動している macOS
• Xcode で少なくとも 1 つのプロジェクト／ワークスペースを開いていること

ステップ 1：Xcode で MCP を有効にする

1. Xcode の 設定（Cmd+,）を開きます
2. Intelligence タブに移動します
3. Enable Model Context Protocol にチェックを入れます
4. Xcode Tools の切り替えがオンになっていることを確認します

この切り替えがオフの場合、xcrun mcpbridge は接続しますが、ツールを返しません。

ステップ 2：MCP クライアントを接続する

Claude Code

claude mcp add --transport stdio xcode -- xcrun mcpbridge

確認方法：claude mcp list に xcode サーバーが表示されます。

Codex

codex mcp add xcode -- xcrun mcpbridge

Cursor

プロジェクトのルートにある .cursor/mcp.json を作成または編集します。

{
  "mcpServers": {
    "xcode": {
      "command": "xcrun",
      "args": ["mcpbridge"]
    }
  }
}

Cursor 固有の注意事項：Cursor は厳格な MCP クライアントです。Xcode の mcpbridge は、ツールで outputSchema が宣言されている場合に structuredContent を省略します。これは MCP 仕様に違反します。Cursor がレスポンスを拒否する場合は、プロキシとして XcodeMCPWrapper を使用してください。

{
  "mcpServers": {
    "xcode": {
      "command": "/path/to/XcodeMCPWrapper",
      "args": []
    }
  }
}

VS Code + GitHub Copilot

.vscode/mcp.json を作成または編集します。

{
  "servers": {
    "xcode": {
      "type": "stdio",
      "command": "xcrun",
      "args": ["mcpbridge"]
    }
  }
}

Gemini CLI

gemini mcp add xcode -- xcrun mcpbridge

ステップ 3：接続を確認する

設定後、XcodeListWindows（パラメーターなし）を呼び出します。次のように表示されます。

tabIdentifier: <uuid>, workspacePath: /path/to/YourProject.xcodeproj

空のリストが表示される場合は、Xcode でプロジェクトが開いていることを確認してください。

権限ダイアログ

MCP クライアントが初めて接続すると、Xcode に権限ダイアログが表示されます。

• 接続元のプロセスを PID で識別します
• MCP ツールへのアクセス許可を求めます
• Xcode の UI で承認する必要があります（ターミナルではありません）

PID に基づく承認：権限はプロセスごとに付与されます。クライアントが再起動すると（新しい PID になると）、ダイアログが再び表示されます。これは想定された動作です。

複数の Xcode インスタンスの指定

複数の Xcode インスタンスが実行されている場合：

自動検出（デフォルト）

mcpbridge は、次のフォールバック順で自動選択します。

1. Xcode プロセスが 1 つだけ実行されている場合 → そのプロセスを使用します
2. 複数ある場合 → xcode-select と一致するものを使用します
3. ない場合 → エラーで終了します

PID の手動選択

特定のインスタンスを指定するには、MCP_XCODE_PID を設定します。

# Find Xcode PIDs
pgrep -x Xcode

# Claude Code with specific PID
claude mcp add --transport stdio xcode -- env MCP_XCODE_PID=12345 xcrun mcpbridge

セッション ID（任意）

MCP_XCODE_SESSION_ID は、ツールセッションに安定した UUID を設定します。再接続をまたいだやり取りの追跡に便利です。

トラブルシューティング

digraph troubleshoot {
    rankdir=TB;
    "Connection failed?" [shape=diamond];
    "tools/list empty?" [shape=diamond];
    "Wrong project?" [shape=diamond];
    "Repeated permission prompts?" [shape=diamond];
    "Client rejects responses?" [shape=diamond];

    "Check Xcode running + toggle on" [shape=box];
    "Open a project in Xcode" [shape=box];
    "Use MCP_XCODE_PID or check tab targeting" [shape=box];
    "Expected: PID changes on restart" [shape=box];
    "Use XcodeMCPWrapper proxy" [shape=box];

    "Connection failed?" -> "Check Xcode running + toggle on" [label="refused/timeout"];
    "Connection failed?" -> "tools/list empty?" [label="connects OK"];
    "tools/list empty?" -> "Open a project in Xcode" [label="no tools"];
    "tools/list empty?" -> "Wrong project?" [label="tools listed"];
    "Wrong project?" -> "Use MCP_XCODE_PID or check tab targeting" [label="yes"];
    "Wrong project?" -> "Repeated permission prompts?" [label="no"];
    "Repeated permission prompts?" -> "Expected: PID changes on restart" [label="yes"];
    "Repeated permission prompts?" -> "Client rejects responses?" [label="no"];
    "Client rejects responses?" -> "Use XcodeMCPWrapper proxy" [label="strict client (Cursor)"];
}

よくある問題

症状	原因	対処方法
"Connection refused"	Xcode が起動していない、または MCP の切り替えがオフ	Xcode を起動し、「設定」>「Intelligence」で MCP を有効にします
tools/list が空を返す	プロジェクトが開いていない、または権限が付与されていない	プロジェクトを開き、Xcode に権限ダイアログが表示されていないか確認します
ツールが別のプロジェクトを対象にする	Xcode のウィンドウが複数ある、またはタブが異なる	XcodeListWindows を呼び出し、正しい tabIdentifier を使用します
権限の確認が繰り返し表示される	クライアントが再起動した（新しい PID）	想定された動作です — 毎回承認してください
Cursor／厳格なクライアントのエラー	レスポンスに structuredContent がない	プロキシとして XcodeMCPWrapper を使用します
"No such command: mcpbridge"	Xcode < 26.3	Xcode 26.3+ にアップデートします
ツールの呼び出しが遅い／応答しない	大規模プロジェクトのインデックス作成	Xcode のインデックス作成が完了するまで待ちます

Xcode 内蔵アシスタントの設定

Xcode は、内蔵アシスタント向けの MCP サーバーにも対応しています。設定ファイルは次の場所にあります。

~/Library/Developer/Xcode/CodingAssistant/codex
~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig

これらは Xcode の内部アシスタントを設定するためのもので、外部 MCP クライアントのセットアップとは別です。

リソース

ドキュメント：/xcode/mcp-server

スキル：axiom-xcode-mcp-tools、axiom-xcode-mcp-ref