Unity MCP 統合フレームワーク

English Version

はじめて使う方は、図つきの導入ガイド Unity MCP のはじめかた から始めてください。

Unity Editor を AI エージェントに開放するフレームワークです。人が手で実行しても、スクリプトから呼んでも、同じ経路を通ります。

主な経路はコマンドラインの isuzu-unity-cli です。配布している実行ファイルはネイティブなので、Node も .NET ランタイムも要りません。

MCP クライアントは、Editor 自身が公開する Streamable HTTP エンドポイント http://127.0.0.1:<port>/mcp に直接つながります。別プロセスの MCP サーバーはありません。

ツールは C# の static メソッドに [McpTool] を付けるだけで定義できます。CLI と MCP の両方に配信されます。

ポートはプロジェクトのパスから決まるので、Editor を再起動しても変わりません。ツールを呼ぶには bearer token が必要です。

必要条件

• Unity Editor 2022.3 以降。EditMode スイートは 2022.3.22f1 / 6000.0.35f1 / 6000.5.10f1 で検証しています
• Git クライアント 2.14.0 以降を PATH に通しておいてください。Unity の Package Manager が git URL のパッケージを取得するのに使います（Unity のマニュアル）。下の VPM リポジトリから入れる場合は要りません
• com.unity.nuget.newtonsoft-json 3.2.1。依存として自動で解決されます
• CLI に Node.js は不要です。dotnet tool install でインストールする場合のみ .NET SDK が必要です

Unity 6.5 以降では、instanceId が JSON の数値ではなく文字列で返ります。64 ビットの EntityId は JavaScript の数値では正確に表せないためです。引数の instance_id は数値と文字列のどちらでも受け付けます。

インストール

Unity の Package Manager で Add package from git URL を選び、次の URL を入力します。

https://github.com/isuzu-shiranui/UnityMCP.git?path=jp.shiranui-isuzu.unity-mcp

VCC（VRChat Creator Companion）と ALCOM では、VPM リポジトリからも入れられます。どちらもパッケージを zip でダウンロードするので、この経路に Git は要りません。

https://unity-mcp.shiranui-isuzu.dev/vpm.json

この URL を貼り付ける場所は、VCC では Settings ページの Packages タブにある Add Repository です。ALCOM では「パッケージ&テンプレート」の「VPMリポジトリ」ページにある「VPMリポジトリを追加」です。追加すると、プロジェクトのパッケージ一覧に Unity MCP が並びます。ワンクリックで追加するリンクは、導入ガイドの VCC・ALCOM をお使いの場合 にあります。

CLI をインストールします。

# Windows
irm https://raw.githubusercontent.com/isuzu-shiranui/UnityMCP/main/install.ps1 | iex

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/isuzu-shiranui/UnityMCP/main/install.sh | sh

# .NET SDK がある場合
dotnet tool install -g IsuzuUnityCli

GitHub Releases から実行ファイルを直接ダウンロードすることもできます。ファイル名は isuzu-unity-cli-win-x64.exe / -osx-arm64 / -osx-x64 / -linux-x64 で、SHA256SUMS で検証できます。Editor の Preferences > Unity MCP ページにある「Install CLI」ボタンからも入ります。

インストールできたら、Claude Code / Codex 向けのスキルを導入します。

isuzu-unity-cli setup

最初のコマンド

Editor がプロジェクトを開くとサーバーが起動し、descriptor ファイルを公開します。CLI はそれを読むので、ポートやトークンの指定は要りません。

isuzu-unity-cli projects                  # 起動中の Editor 一覧
isuzu-unity-cli health                    # サーバーの状態
isuzu-unity-cli tools                     # 利用可能なツール
isuzu-unity-cli call play_mode_status     # ツールの実行
isuzu-unity-cli verify                    # 再コンパイル → エラー抽出 → コンソールのエラー

verify は、スクリプトを編集したあとの再コンパイルとエラー収集を 1 回の呼び出しにまとめます。--test を付けるとテストも実行します。

Editor が複数起動しているときは --project <name> で選びます。プロジェクトのディレクトリ内で実行していれば、自動で選ばれます。全コマンドは CLI リファレンス にあります。

MCP クライアントとの連携

Claude Code の場合はこうなります。

claude mcp add --transport http isuzu-unity http://127.0.0.1:<port>/mcp --header "Authorization: Bearer <token>"

ポートは isuzu-unity-cli doctor の「Running Editors」に出る URL に含まれています。トークンはそこには出ません。Editor の Preferences > Unity MCP ページを開いてください。Connection の Bearer トークンの行にある「Copy」を押すとコピーできます。

トークンを自分で扱いたくない場合は、CLI に登録を任せられます。

isuzu-unity-cli setup --mcp --agent claude-code

--agent は claude-code / claude-desktop / codex / cursor / gemini / vscode から選べます。

Claude Desktop には拡張機能バンドルもあります。Releases の isuzu-unity-cli.mcpb をダブルクリックすると入ります。

クライアントごとの設定、Claude Desktop 向けの stdio ブリッジ、プロトコル上の性質は MCP クライアントの接続 にあります。

ツール

Editor は最大で 88 個のツールを公開します。Timeline の 9 個と Recorder の 2 個は、com.unity.timeline と com.unity.recorder があるときだけ現れます。test_run と test_results は com.unity.test-framework があるときだけです。どれも入っていないプロジェクトが公開するのは 75 個のツールです。

一覧と注意点は ツール一覧 にあります。

MCP の URL に ?group=diagnostics,authoring のようにグループを付けると、tools/list がそのグループだけを返します。

ツールの追加

Editor 側にメソッドを 1 つ書くだけです。

using System.Linq;
using UnityMCP.Editor.Core;
using UnityMCP.Editor.Core.Attributes;

internal static class MyTools
{
    [McpTool(
        "asset_find_by_type",
        "Find project assets of a given type. Prefer a narrow type and a small limit.",
        Idempotency = McpIdempotency.Safe)]
    public static string[] FindByType(
        [McpArg("type", "Unity type name, e.g. Material.")] string type,
        [McpArg("limit", "Maximum paths to return.")] int limit = 50)
    {
        return UnityEditor.AssetDatabase.FindAssets($"t:{type}")
            .Take(limit)
            .Select(UnityEditor.AssetDatabase.GUIDToAssetPath)
            .ToArray();
    }
}

これだけで /tools に現れ、MCP クライアントと CLI の両方から呼べます。JSON Schema はシグネチャから生成されます。

[McpTool] の属性は 4 つあります。

ツール名は ^[a-z][a-z0-9_]{0,63}$ です。説明文は、モデルがそのツールを選ぶ唯一の手がかりになります。何をするかだけでなく、どういうときに使うかを書いてください。

C# を書かずに、JSON ファイルでツールを追加することもできます。定義ツール を参照してください。

実測値

3 つの経路は同じ結果を返します。ベンチマークは時間を測る前にそれを検証し、REST の result、MCP の structuredContent、CLI の標準出力が一致しなければ、1 回も計測せずに終了します。

CLI は 1 回の呼び出しごとにプロセスと TCP 接続を作り直します。ヒープ増加の差は、その接続ごとのバッファであって、ツールの処理ではありません。接続を保つ経路が速いのは当然で、CLI が引き換えに得ているのは、クライアントの設定も常駐プロセスも要らないことです。

CLI の 1 呼び出しは、プロセスの生成から出力までで 24.0 ms でした。そのうち Main に入るまでが 15.8 ms です。残る 8.2 ms が、引数の解析、Editor の発見、接続、往復、出力のすべてです。Editor との往復そのものは 3.4 ms でした。UNITY_MCP_TRACE=1 を付けると、この内訳が出ます。

測定に使ったのは Core i9-14900KF と Windows 11 (10.0.26200) です。.NET は 10.0.100、Unity は 6000.5.10f1 です。経路ごとに 30 回計測し、その前に 3 回のウォームアップが入ります。計測中は Unity のプロセスが 9 個動いていました。再現するには scripts/bench-cli-vs-mcp.ps1 を実行してください。何を測っているかの定義は scripts/README.md にあります。

ドキュメント

• ツール一覧: 88 個のツールの表と注意点
• MCP クライアントの接続: クライアントごとの設定、Claude Desktop ブリッジ、プロトコルの性質
• CLI リファレンス: 全コマンド、プロジェクトの選択、終了コード、マシン上に置くもの
• 定義ツール: JSON ファイルで probe / script / sequence ツールを追加する
• Editor 入力の合成・記録・再生: input_pointer / input_key / input_record / input_replay
• アーキテクチャ: 経路図、Editor 側のクラス、設定、テスト
• トラブルシューティング
• セキュリティ
• v3 からの移行
• CHANGELOG

セキュリティ

• サーバーは 127.0.0.1 にだけバインドします。OPTIONS を除く全リクエストに bearer token が必要です。OPTIONS は CORS のプリフライトで、本文のない 204 を返すだけです
• descriptor ファイルとトークンファイルは資格情報として扱ってください。これらを読めれば、Editor 内でコードを実行できます
• プレイヤービルドには、Development Build を含めて一切入りません。ソースはすべて Editor/ 配下にあり、アセンブリ定義が Editor 限定です。CI が毎回検査します

詳細は セキュリティ にあります。

ライセンス

MIT