Claude Media
Unity公式MCPサーバーをClaude Codeで使う方法
Claude CodeMCPClaude連携チュートリアル

Unity公式MCPサーバーをClaude Codeで使う方法

Unity Editor内蔵のMCPブリッジをClaude Codeに接続する設定手順と、接続承認の仕組み・トラブルシューティングを公式マニュアルに基づいて確認します。

読了目安 約11分

Unity公式MCPサーバーとは

Unity MCPは、Unity Editorに組み込まれたMCP(Model Context Protocol)ブリッジです。Claude CodeやCursorのようなMCP対応クライアントをUnity Editorに接続し、シーン作成・アセット管理・コード生成といった作業を標準化されたツール呼び出しで自動化します。パッケージcom.unity.ai.assistantに同梱されており、Unity 6以降のEditorで動きます。

Editorが起動するとMCPブリッジが自動的に立ち上がり、ローカルのIPCチャネル(Windowsは名前付きパイプ、macOS/LinuxはUnixソケット)を開きます。~/.unity/relay/には中継用のリレーバイナリが自動インストールされ、これがAIクライアントから起動されるMCPサーバープロセスの実体です。リレーはブリッジに接続し、Unityの機能をMCPツールとして公開します。

構成はシンプルです。AIクライアント(Claude Codeなど)がMCPプロトコル経由でリレーバイナリを起動し、リレーがIPCでUnity Editor内のMCPブリッジと通信します。ブリッジ側のMcpToolRegistryが登録済みツールを管理し、リクエストをEditor内の処理へ橋渡しします。

前提条件

Claude Codeから接続するには次の2点が要ります。

  • Unity 6(6000.0)以降で、com.unity.ai.assistantパッケージが導入されたプロジェクト
  • MCP対応のAIクライアント(Claude Code、Cursor、Windsurf、Claude Desktopのいずれか)

本記事が参照する公式マニュアルは、com.unity.ai.assistantパッケージ2.0.0-pre.1(プレリリース版)のドキュメントです。正式リリースまでに手順や設定項目が変わる可能性があります。Claude Code側でMCPサーバーを追加する一般的な仕組み(claude mcp addの構文やスコープ)はClaude Code MCP設定ガイドで扱っているので、初めてMCPサーバーを足す場合はあわせて確認してください。

Claude Codeへ接続する手順

ステップ1: Unity側のブリッジを確認する

Unity EditorでEdit > Project Settings > AI > Unity MCPを開きます。Bridge statusが緑の「Running」になっていれば起動済みです。「Stopped」と表示されている場合はStartを選択します。ブリッジ自体はEditor起動時に自動で立ち上がる設計で、手動操作が要るのは止まっているときだけです。

ステップ2: Claude Code側にMCPサーバーを登録する

Unity MCP設定ページの「Integrations」セクションを開き、Claude Codeを選んで「Configure」を実行すると自動で設定されます。手動で設定する場合は、Claude CodeのMCPサーバー設定に次を追加します。

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

リレーバイナリのパスはOSとアーキテクチャで変わります。

プラットフォームリレーバイナリのパス
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
Windowsリレーバイナリのパス%USERPROFILE%\.unity\relay\relay_win.exe
Linuxリレーバイナリのパス~/.unity/relay/relay_linux

argsの--mcpフラグは必須です。リレーバイナリはMCPサーバー以外の動作モードも持つため、このフラグでMCPサーバーとして動かすことを明示します。

設定前に、リレーバイナリが実際にインストールされているかを確認しておくと事故が減ります。

ls -la ~/.unity/relay/

ファイルが無い場合はUnity Editorを一度再起動してください。インストーラーはEditor起動時にパッケージ内のバイナリをコピーします。

ステップ3: 接続を承認する

Claude Codeのような外部MCPクライアントが初めて接続すると、Unity MCP設定ページの「Pending Connections」に保留中の接続として表示されます。Acceptを選ぶまでツールは呼び出せません。承認済みのクライアントは、次回以降は再承認なしで自動的に再接続します。

接続経路によって承認の要否が変わります。

接続経路承認想定クライアント
AI Gateway(Unity Assistant経由)承認自動承認・操作不要想定クライアントUnity Assistant
Direct connection(外部MCPクライアント)承認Project Settingsのダイアログで手動承認想定クライアントClaude Code、Cursorなど

Claude CodeはDirect connectionの扱いになるため、初回接続時は必ずこの承認操作が要ります。

ステップ4: 動作確認する

UnityとClaude Codeの両方を起動した状態で、Unity MCP設定ページの「Connected Clients」にクライアントが表示されていれば接続は成立しています。Claude Code側でもUnity_ManageSceneやUnity_ReadConsoleといったツール名が一覧できます。

簡単な動作確認として、Claude Codeで次のように指示します。

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

クライアントがUnity_ReadConsoleツールを使ってUnityのコンソール出力を取得し、要約を返せば設定は完了です。

Unity MCPが公開する主な機能

公式マニュアルが挙げる主要機能は次の4つです。

機能内容
ツール登録システム内容属性・インターフェース・ランタイムAPIのいずれかでMCPツールを作成・登録できる
組み込みツール内容シーン管理、アセット操作、スクリプト編集、コンソールアクセスを標準で自動化
動的検出内容Editor起動時にツールを自動的に検出・登録する
マルチクライアント対応内容複数のMCPクライアントが同一Unityインスタンスへ同時に接続できる

個別のツールの有効・無効は、Project Settingsの「Unity MCP」ページにあるツール一覧のトグルで切り替えられます。

カスタムツールを登録する

Unity MCPは属性ベースでカスタムツールを追加できます。もっとも単純な形は、staticメソッドに[McpTool]を付ける方法です。

using Unity.AI.MCP.Editor.ToolRegistry;
 
[McpTool("my_tool", "Description of what this tool does")]
public static object MyTool(MyParameters parameters)
{
    return new { success = true, message = $"Processed {parameters.Name}" };
}
 
public class MyParameters
{
    [McpDescription("Target name")]
    public string Name { get; set; } = "default";
}

Editor起動時にMcpToolRegistryがTypeCacheでアセンブリを走査し、[McpTool]が付いたメソッドを自動で発見・登録します。パラメータの型からJSONスキーマも自動生成されるため、スキーマを手書きする必要はありません。状態を持たせたいツールはクラス実装(IUnityMcpTool<T>)、実行時に動的に登録・解除したい場合はMcpToolRegistry.RegisterToolのランタイムAPIを使います。属性ベースでツールスキーマを生成する設計は、.NET公式のMCP C# SDKが採用する[McpServerTool]パターンとも発想が近く、Unity固有の独自属性である点だけが異なります。

よくあるつまずき

ブリッジが起動しないケースの多くは、スクリプトのコンパイルエラーかパッケージの導入不備が原因です。Unity Consoleでコンパイルエラーを解消し、Edit > Project Settings > AI > Unity MCPでStartを選び直すと復旧します。

クライアントが接続できない場合は、--mcpフラグの付け忘れと、リレーバイナリのパス指定ミスが典型的な原因です。設定を手書きした場合は、Unity MCP設定ページの「Integrations」から自動設定し直す方が確実です。

接続はできてもツールが呼び出せない場合は、Pending Connectionsで承認待ちのままになっていないかを確認します。ステップ3の承認操作を忘れると、接続自体は成立していてもツール呼び出しはすべて失敗します。

カスタムツールが一覧に出てこない場合は、[McpTool]を付けたメソッドがpublic staticになっているか、クラスベースの場合はIUnityMcpToolを実装しパラメータなしコンストラクタを持っているかを確認します。ツール自体がUnity MCP設定ページで無効化されていないかも見ておくとよいでしょう。Unity Editor全体のMCP接続で切り分けが必要なときは、クライアント側の設定・起動・認証・ツール表示を4層に分けて追うMCPサーバーに接続できないときの切り分け手順が一般的な原因の絞り込みに使えます。

リレーバイナリ自体が無いケースも起きます。インストーラー(ServerInstaller)はEditor起動時に走りますが、途中で中断されたりパッケージディレクトリにアクセスできなかったりすると失敗します。Editorを再起動してインストーラーを再実行させるのがまず試すべき対処です。それでも解決しない場合は、Unity MCP設定ページの「Locate Server」ボタンでパッケージに同梱されたバイナリを見つけ、手動でコピーする回避策があります。

応答が遅い・タイムアウトする場合は、Unityがアセットのインポートやビルド、コンパイルなど重い処理で塞がっていないかを確認します。進捗バーが表示されているならその処理の完了を待ち、解消しなければEditorを再起動してキャッシュ状態をクリアします。同時に接続するMCPクライアントの数を減らすことも有効です。

Unity MCP設定ページの「Show Debug Logs」を有効にすると、接続試行・ツール検出の詳細・コマンド実行のトレース・エラー情報がログに出るため、上記で解決しない場合の次の手がかりになります。

Unreal MCPとのセキュリティモデルの違い

同じ「ゲームエンジン公式のMCPサーバー」でも、Epic GamesのUnreal MCPはUnity MCPと接続モデルが異なります。Unreal MCPはHTTP/SSEのみをサポートし、デフォルトでlocalhostへのバインドに限定される一方、認証レイヤーそのものを持ちません。Unreal MCP側のドキュメントは、ローカルマシン以外への公開を想定した安全設計ではないと明記しています。

Unity MCPは逆に、外部クライアントからのDirect connectionを既定でユーザー承認必須にしています。AI Gateway経由の接続だけが自動承認の例外です。同じ「エディタに組み込まれたMCPサーバー」という設計思想でも、外部クライアントの接続をどこで止めるかという判断がエンジンごとに分かれている点は、ローカルMCPサーバーを評価するときの着眼点になります。

まとめ

Unity公式MCPサーバーは、com.unity.ai.assistantパッケージに同梱されたリレーバイナリとEditor内蔵のブリッジで動きます。Claude Code側でやることは、リレーバイナリのパスを--mcpフラグ付きで登録し、Unity側のPending Connectionsで初回接続を承認するだけです。組み込みツールでシーンやコンソールの操作はすぐ試せ、[McpTool]属性を使えば自作ツールも同じ仕組みで公開できます。接続できないときは、まずブリッジの起動状態・リレーバイナリの有無・--mcpフラグの3点を疑うと切り分けが早くなります。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →