Unity MCP完全ガイド：Claude Code・Codex・Gemini・CursorをUnity Editorに接続する

by

Unity AI完全マスターシリーズ
第1回 — Unity AI Assistant入門：Ask・Plan・Agentモード完全解説
第2回 — Unity MCP完全ガイド：Claude Code・Codex・Gemini・CursorをUnity Editorに接続する （この記事）
第3回 — Unity MCPカスタムツールの作り方：McpTool Deep Diveと4つの登録方式
第4回 — Unity SkillsシステムでAIワークフローを自動化する：SKILL.md完全ガイド
Appendix — Unity MCPビルトインツール完全リファレンス：51個のツールパラメータ・有効化ガイド
第5回 — Unity AI AssistantのProject Overview自動生成：AIがプロジェクトを理解するようにする方法
第6回 — Unity AI Assistant × Profiler：性能ボトルネックを自然言語で診断する実践ガイド

Claude CodeやCodexでUnityのプロジェクトフォルダを開いていれば「接続されている」と思いがちです。実際、その状態でもC#スクリプトを読んで修正することは可能です。しかしそれはファイルシステムへのアクセスにすぎず、Unity Editorと「対話している」とは言えません。

AIとUnity Editor間の真の「対話」は、Unity MCP(Model Context Protocol)Serverを通じて行われます。「現在のシーンに存在するオブジェクトのコンポーネント一覧を教えて」「コンソールに溜まったエラーメッセージの原因を調べて修正して」——こうした要求は、ディスク上のファイルを読むだけでは解決できません。実行中のUnity Editor自体を操作する必要があります。Unity MCPはUnity EditorをMCPサーバーとして公開し、Claude CodeやCodexといった外部AIクライアントがエディター内部の状態を直接照会・操作できるようにします。Unity AI Assistant 2.7(Unity 6.0.66f2以降)で安全に使用できます。ただし、Unity AI Assistantは現在ベータ版です。既知の問題があり、アップデートごとに動作が変わる可能性があります。プロダクションワークフローへ直接組み込むよりも、可能性を探る段階として活用することをお勧めします。

TL;DR
– Unityプロジェクトフォルダを読み込むことと、Unity Editorを操作することは別物です。Unity MCPは後者を可能にします——Unity Editor自体をMCPサーバーとして公開し、AIが実行中のエディター状態を直接照会・操作します。
– リレーバイナリ(~/.unity/relay/)がMCPプロトコル↔IPC変換を担い、プラットフォームごとにパスが異なります。
– Claude Code接続：リレーの絶対パスをMCP設定ファイルに追加 → Unityで手動承認。
– AI GatewayはUnity Editor内でClaude Codeを直接実行でき、個別の接続承認が不要です。
– Unity AI Assistantは現在ベータ版です。既知のバグがあり、アップデートごとに動作が変わる可能性があるため、プロダクションよりも探索段階での活用をお勧めします。

目次
– Unity MCPとは
– 2種類のMCP：方向がまったく逆
– アーキテクチャ：ブリッジ・リレー・IPC 3層構造
– Claude Code接続設定
– Cursor接続設定
– AI Gateway：Unity内でClaude Codeを実行する
– トラブルシューティング

Unity MCPとは

Unity MCPは、Claude CodeやCodexといった外部AIクライアントがUnity Editor内のシーン・アセット・スクリプトを直接操作できるよう、Unity Editor自体をMCPサーバーとして公開するシステムです。MCP(Model Context Protocol)はAIクライアントとサーバー間の標準通信規約であり、Unityはこの規約に準拠したサーバー役を担います。

「Unity AI Assistant内でGit MCPサーバーを使う」とは方向が逆になります。混同しやすい2つの概念をまず整理します。

2種類のMCP：方向がまったく逆

Unity AI Assistantには名前は似ていますが、まったく異なる2つのMCP機能が存在します。

区分 MCP Client (Assistant MCP Extensions) Unity MCP Server
方向 Assistant → 外部MCPサーバー 外部AIクライアント → Unity Editor
Unityの役割 MCPクライアント MCPサーバー
設定場所 Edit > Project Settings > AI > Assistant MCP Extensions Edit > Project Settings > AI > Unity MCP Server
代表的な用途 AssistantからBlenderを操作 Claude CodeでUnityシーンのオブジェクトを操作

本記事で扱うのは右側、Unity MCP Server(以下Unity MCP)です。Claude CodeやCodexがUnityを「Tools Server」として見なし、必要なToolを呼び出してUnity Editorに命令を下す構造です。

アーキテクチャ：ブリッジ・リレー・IPC 3層構造

AIクライアントとUnity MCP Serverがどのような過程で接続・通信するかを理解することで、活用度だけでなくトラブルシューティングも格段に容易になります。

AIクライアント Claude Code / Codex MCP (stdio) ← 結果 リレー層 Relayバイナリ ~/.unity/relay/ relay_win.exe 等 MCP↔IPCプロトコル変換 IPC層 ← 結果 ブリッジ層 Unity MCPブリッジ Unity Editor内部 McpToolRegistry Built-in + Custom Tools ツール登録・実行管理 ツール呼出し (dispatch) → ← 結果返却 Unity_ReadConsole コンソール読取り get_components コンポーネント照会 + Custom Tools [McpTool]属性 リクエスト (tools/call) 結果 (result)

リレー層：stdio ↔ IPC変換

AIクライアントはMCP標準に従い、stdio(Standard Input/Output、標準入出力)でツールサーバーと通信します。しかしUnity Editor内部のMCPブリッジが使用するチャネルはIPC(Inter-Process Communication、プロセス間通信)です。この2つのプロトコルは直接接続できないため、中間に変換器が必要です。

Relayバイナリ(~/.unity/relay/)がこの役割を担います。AIクライアントがrelayプロセスを子プロセスとして起動しstdio経由でMCPメッセージを渡すと、relayはそれをIPC形式に変換してUnity EditorのMCPブリッジに転送します。Unity初回起動時にServerInstallerがプラットフォームに合ったリレーバイナリを~/.unity/relay/パスに自動インストールします。

IPC層：プラットフォーム別ローカルソケット

Unity Editorが起動すると、MCPブリッジがローカルIPCチャネルを自動的に開き、リレーの接続を待ちます。IPC実装はプラットフォームによって異なります。

プラットフォーム IPC方式
Windows Named Pipe
macOS / Linux Unix Domain Socket

IPCは同じマシン上のプロセス間通信のため、ネットワーク設定は不要です。リレーバイナリとUnity Editorは必ず同じマシンで実行している必要があります。

接続が確立されるまでの流れ（Windows基準）

① Unity Editor起動 — MCPブリッジがNamed Pipeを開き、接続情報を~/.unity/mcp/connections/に記録します。

# ~/.unity/mcp/connections/bridge-9beba166-74996.json
{
  "connection_type": "named_pipe",
  "connection_path": "\\\\.\\pipe\\unity-mcp-9beba166-74996",
  "project_path": "D:\\Unity\\Projects\\MyGame",
  "editor_pid": 74996
}

② AIクライアントがrelayを子プロセスとして起動 — Claude CodeがMCP設定ファイルのcommandパスでrelay_win.exeを起動し、stdioチャネルを確保します。

③ relayがbridgeファイルを読み込みNamed Pipeに接続 — relayは~/.unity/mcp/connections/bridge-*.jsonをスキャンし、connection_path(\\.\pipe\unity-mcp-9beba166-74996)へのNamed Pipe接続を試みます。Unity EditorがこのリクエストをAcceptするとIPCチャネルが完成します。

④ AIクライアント ↔ Unity Editor通信開始 — Claude Codeがstdio経由でtools/listをrelayに送信し、relayはそれをIPCに変換してUnity MCPブリッジに転送します。ブリッジが登録済みツール一覧を返すと、Claude CodeはUnity Editorと完全に接続された状態になります。

ブリッジ層：McpToolRegistry

Unity Editor内部のMCPブリッジはMcpToolRegistryを中心に動作します。パッケージインストール時にUnity_ReadConsoleやget_componentsなどのビルトインツールが自動登録され、[McpTool]属性で宣言したカスタムメソッドも同じレジストリに登録されてAIクライアントに公開されます。AIがツールを呼び出すと、ブリッジはレジストリから対象ツールを探してUnity Editor APIを実行し、結果をIPC → relay → MCPの経路で返します。

接続承認の方式
– 外部MCPクライアントの直接接続 — 初回接続時にProject Settings > AI > Unity MCP > Pending Connectionsでの手動承認が必要です。承認済みのクライアントは以降のセッションから自動的に再接続されます。
– AI Gateway — 手動承認なしで自動接続されます。

ツール探索と呼び出しの流れ

AIクライアントがrelayに接続すると、すぐにtools/listリクエストを送信します。このリクエストはrelay → IPC → Unity MCPブリッジ → McpToolRegistryへと届き、レジストリに登録されたすべてのツールの名前・説明・入力スキーマが一覧として返されます。AIクライアントはこの一覧をコンテキストとして保持します。

その後ユーザーのリクエストが来ると、LLMが各ツールのdescriptionフィールドを読んで意味的にマッチングし、どのツールを使うかを判断します。アルゴリズムではなく、LLMの推論がツールを選びます。選択が終わるとtools/callリクエストをrelayに渡し、IPC → ブリッジ → 対象ツールメソッド実行 → 結果返却の順に処理されます。

descriptionがルーティングキーです。[McpTool]属性に説明を具体的に記述するほど、LLMが適切な状況でそのツールを選択する可能性が高まります。

Claude Code接続設定

ステップ1：パッケージのインストール確認

Package Managerでcom.unity.ai.assistantがインストールされている必要があります。Unity AI AssistantはUnity 6.0.60f1以降で動作しますが、そのバージョンには有効な署名を持つパッケージが無効な署名として表示されるバグがあります。実際にはUnity 6.0.66f2以降の使用が安全です。Generators(アセット生成ツール)を使用する場合はUnity 6.3(6000.3)以降が必要で、同じ理由から6.3.5f2以降を推奨します。

ステップ2：Unity MCPサーバーの起動

Edit > Project Settings > AI > Unity MCP Serverに移動します。Status項目がRunningであれば準備完了です。StoppedであればStartボタンをクリックします。

Project Settings > AI > Unity MCP ServerでStatusがRunningと表示された画面

ステップ3：Claude Code設定ファイルの編集

MCPサーバー設定は、スコープに応じて以下2つのファイルのいずれかに追加します。ファイルが存在しない場合は新規作成してください。

スコープ ファイルの場所 特徴
プロジェクト プロジェクトルート/.mcp.json gitコミット可能、チーム全体で共有。個人利用時は.gitignoreに追加
現在のユーザー ~/.claude.json 現在のアカウントのすべてのプロジェクトに適用

~/.claude.jsonのパスはOSによって異なります。

OS パス
Windows C:\Users\YourName\.claude.json
macOS /Users/YourName/.claude.json
Linux /home/YourName/.claude.json

リレーパスはマシンごとに絶対パスが異なるため、.mcp.jsonをgitにコミットする場合はチームメンバーそれぞれが自分のパスに書き換える必要があります。個人利用目的であれば.mcp.jsonを.gitignoreに追加して他のメンバーの設定への影響を防ぐか、Claude Codeのグローバル設定ファイル~/.claude.jsonを編集してください。選択したファイルに以下の内容を追加します。

Windows：

{
  "mcpServers": {
    "unity-mcp": {
      "command": "C:\\Users\\YourName\\.unity\\relay\\relay_win.exe",
      "args": ["--mcp"]
    }
  }
}

macOS (Apple Silicon)：

{
  "mcpServers": {
    "unity-mcp": {
      "command": "/Users/YourName/.unity/relay/relay_mac_arm64.app/Contents/MacOS/relay_mac_arm64",
      "args": ["--mcp"]
    }
  }
}

~チルダ表記はクライアントが展開しない場合があるため、必ず絶対パスを使用してください。これは設定失敗の最も多い原因です——設定後にUnity MCP Serverが正常動作しない場合は、まず絶対パスで記述されているかを確認してください。

プラットフォーム別リレーパス

プラットフォーム リレー実行ファイルパス
Windows %USERPROFILE%\.unity\relay\relay_win.exe
macOS (Apple Silicon) ~/.unity/relay/relay_mac_arm64.app/Contents/MacOS/relay_mac_arm64
macOS (Intel) ~/.unity/relay/relay_mac_x64.app/Contents/MacOS/relay_mac_x64
Linux ~/.unity/relay/relay_linux

ステップ4：接続の承認

Claude Codeを起動するとUnity EditorにNew MCP Connection承認ウィンドウが表示され、Project Settings > AI > Unity MCP Server > Pending Connectionsセクションに接続リクエストが現れます。Acceptをクリックしてください。承認済みのクライアントは以降のセッションから自動的に再接続されます。

Unity EditorにNew MCP Connection承認ウィンドウが表示された画面 Project Settings > AI > Unity MCP Pending Connectionsに接続リクエストが表示された画面

ステップ5：接続テスト

Claude Codeで以下のプロンプトを入力して、ツール呼び出しが正常に動作するか確認します。

Read the Unity console messages and summarize any warnings or errors.

Claude CodeとUnity MCP Serverが正常に接続されていれば、Unity_ReadConsoleツールが呼び出され、Unityのコンソール出力がClaude Code CLIに取り込まれます。

Cursor接続設定

CursorはClaude CodeとMCP設定の構造が同じです。CursorのMCP設定ファイルに同じ形式でリレーバイナリのパスを指定します。

{
  "mcpServers": {
    "unity-mcp": {
      "command": "C:\\Users\\YourName\\.unity\\relay\\relay_win.exe",
      "args": ["--mcp"]
    }
  }
}

Cursor CLI 2026.02.13以降が必要です。

特定のUnityインスタンスの指定

Unityプロジェクトを複数同時に開いている場合、--project-path引数で対象インスタンスを指定できます。

{
  "mcpServers": {
    "unity": {
      "command": "C:\\Users\\YourName\\.unity\\relay\\relay_win.exe",
      "args": ["--mcp", "--project-path", "D:\\MyUnityProject"]
    }
  }
}
指定方法 コマンドライン引数 環境変数
プロジェクトパス --project-path <path> UNITY_PROJECT_PATH
エディターPID --instance-id <pid> UNITY_INSTANCE_ID

AI Gateway：Unity内でClaude Codeを実行する

別途AIクライアントを使用せず、Unity Assistantウィンドウ内でClaude CodeやCodexをそのまま使いたい場合はAI Gatewayを使用します。AI Gatewayはエージェントセレクター(Kコンポーネント)で切り替えるもので、Unity Editor内でサードパーティのコーディングエージェントを実行する機能です。

AI Gateway経由で接続すると、MCP直接接続と異なり自動承認されます。別途のPending Connections承認手続きはありません。

AI GatewayでClaude CodeがUnity Editorに接続された画面

エージェント 環境変数 バージョン
Claude Code ANTHROPIC_API_KEY 2.1.45以降、別途インストール必要
Cursor CLI — 2026.02.13以降、別途インストール必要
Gemini CLI GEMINI_API_KEY Unityバンドル(インストール不要)
Codex CLI OPENAI_API_KEY Unityバンドル(インストール不要)

全エージェント共通の設定手順

  1. Unity > Settings > Preferences > AI > Gatewayに移動
  2. Agent Typeリストから使用するエージェントを選択
  3. 未インストールのエージェントはバナーのリンクからインストール(Gemini CLI・Codex CLIはUnityバンドル提供のためこの手順を省略)
  4. Environment Variablesを展開してAdd Variableをクリック → 上表の環境変数名とAPIキーを入力
  5. Cursorは環境変数不要。インストールのみで動作

AI GatewayはUnity Editor内でエージェントを統合する素早い入り口です。MCP直接接続は既存のClaude Code・Cursor環境をそのまま維持しながらUnityツールのみを追加する方法です。

トラブルシューティング

ブリッジが起動しない（Stopped状態）

症状：Project Settings > AI > Unity MCP ServerページにStoppedと表示され、クライアントが接続できない。

確認順序：
1. Unity Consoleにコンパイルエラーがないか確認します。コンパイルエラーがあるとブリッジが起動しません。
2. com.unity.ai.assistantパッケージがPackage Managerにインストールされているか確認します。
3. Project Settings > AI > Unity MCP ServerでStartボタンを直接クリックします。
4. 上記3点を確認しても解決しない場合はUnity Editorを再起動します。

リレーバイナリが見つからない

症状：クライアント設定ファイルのcommandパスにファイルが存在しない。

原因：Unity Editor起動時にServerInstallerがバイナリのインストールを完了できなかった場合です。

解決順序：
1. Unity Editorを再起動します(インストーラーが再実行されます)。
2. Packages/com.unity.ai.assistant/RelayApp~/フォルダでバイナリを直接確認します。
3. Unity Consoleにインストール関連の警告がないか確認します。
4. Project Settings > AI > Unity MCPのLocate Serverボタンで手動パスを指定します。

ツールが見つからない

[McpTool]属性で登録したカスタムツールがクライアントから見えない場合です。

チェックリスト：
– Unity Consoleにコンパイルエラーがないことを確認します。
– ツールメソッドがpublic staticであり、[McpTool]属性があるか確認します。
– Project Settings > AI > Unity MCP > Toolsセクションで該当ツールが有効になっているか確認します。
– Show Debug Logsオプションを有効にすると、ツール探索の過程をコンソールで追跡できます。

複数のUnity Editorインスタンスが起動中の場合

症状：コマンドを実行したのに、別のプロジェクトのUnity Editorで反応が起きる。

原因——リレーのエディター探索方式：Unity Editorが起動すると~/.unity/mcp/connections/フォルダに接続ファイルを作成します。

~/.unity/mcp/connections/
  bridge-7ba777b2-65156.json   ← プロジェクトA (pid 65156)
  bridge-9beba166-74996.json   ← プロジェクトB (pid 74996)
  bridge-cf5129b7-83800.json   ← プロジェクトC (pid 83800)

各ファイルにはNamed Pipeパス、プロジェクトパス、エディターPIDが含まれています。

{
  "connection_type": "named_pipe",
  "connection_path": "\\\\.\\pipe\\unity-mcp-9beba166-74996",
  "project_path": "D:\\Unity\\Projects\\MyGame",
  "editor_pid": 74996
}

relayはこのフォルダのbridge-*.jsonファイルをファイル名のアルファベット順にスキャンし、最初のファイルのNamed Pipeに接続します。つまり、起動順序ではなくファイル名に含まれるUUIDのアルファベット順がデフォルトの接続先を決定します。UUIDはプロジェクトごとに固定値のため、どのプロジェクトが最初に接続されるか予測しにくい状況になります。

解決方法：リレーバイナリの引数または環境変数で接続対象エディターを明示します。

指定方法 コマンドライン引数 環境変数
プロジェクトパス指定 --project-path <path> UNITY_PROJECT_PATH
エディターPID指定 --instance-id <pid> UNITY_INSTANCE_ID

PIDは~/.unity/mcp/connections/bridge-*.jsonファイルのeditor_pidフィールド、またはファイル名末尾の数字から確認できます。コマンドライン引数が環境変数より優先されます。マルチエディター環境では、プロジェクトごとに個別のMCP設定ファイルを用意して--project-pathで各プロジェクトを明示することを推奨します。

.mcp.json設定例(--project-path使用)：

{
  "mcpServers": {
    "unity": {
      "command": "C:\\Users\\YourName\\.unity\\relay\\relay_win.exe",
      "args": ["--mcp", "--project-path", "D:\\MyUnityProject"]
    }
  }
}

デバッグログの有効化

トラブルシューティング中はProject Settings > AI > Unity MCP ServerでShow Debug Logsをチェックします。接続試行、ツール探索、コマンド実行追跡、エラー情報がUnity Consoleに出力されます。

まとめ

本記事はUnity AI完全攻略シリーズの第2弾です。第1弾ではUnity AI AssistantをエディターのAsk・Plan・Agentモードで内側から使う方法を扱い、今回の第2弾では同じパッケージが提供するUnity MCPを通じてClaude Code・Codexなど外部AIクライアントを接続する方法を扱いました。

Claude CodeがUnityシーンを直接読み込み、コンソールエラーをリアルタイムで確認し、アセットを操作するワークフロー——Unity AIがなければ複数のプラグインを組み合わせても、このレベルの統合は実現できなかったはずです。

設定自体はリレーバイナリのパスを1つ設定するだけです。ベータ期間中はバージョンアップのたびに動作が変わる可能性があるため、公式リリースノートを定期的に確認することをお勧めします。

カスタムMCPツールの作成([McpTool]属性の活用)やSkillsシステムを通じたワークフローの自動化に興味がある方は、次の記事で詳しく取り上げます。

さらに深く学ぶには

本記事を執筆する際に直接確認した公式ドキュメントです。

合わせて読みたい記事

← 前の記事：第1弾 — Unity AI Assistant完全入門：Ask・Plan・Agentモード  |  次の記事 → 第3弾 — カスタムMCPツール（準備中）

コメントする

© 2026 GameDevLLM.com · All Rights Reserved