{
  "markdown": "# Unity MCP 統合フレームワーク\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n![Version](https://img.shields.io/badge/version-4.0.6-brightgreen)\n![Unity](https://img.shields.io/badge/Unity-2022.3%E2%80%93Unity6-black.svg)\n![.NET](https://img.shields.io/badge/.NET-10-purple.svg)\n![GitHub Stars](https://img.shields.io/github/stars/isuzu-shiranui/UnityMCP?style=social)\n\n[English Version](./README.en.md)\n\nはじめて使う方は、図つきの導入ガイド [Unity MCP のはじめかた](https://unity-mcp.shiranui-isuzu.dev/) から始めてください。\n\nUnity Editor を AI エージェントに開放するフレームワークです。人が手で実行しても、スクリプトから呼んでも、同じ経路を通ります。\n\nUnity プロジェクトなら種類を問いません。VPM リポジトリも用意しているので、VCC（VRChat Creator Companion）や ALCOM からも入れられます。\n\n主な経路はコマンドラインの `isuzu-unity-cli` です。配布している実行ファイルはネイティブなので、Node も .NET ランタイムも要りません。\n\nMCP クライアントは、Editor 自身が公開する Streamable HTTP エンドポイント `http://127.0.0.1:<port>/mcp` に直接つながります。別プロセスの MCP サーバーはありません。Claude Code、Cursor、Codex、Gemini CLI、VS Code、Claude Desktop で確認しています。\n\nツールは C# の static メソッドに `[McpTool]` を付けるだけで定義できます。CLI と MCP の両方に配信されます。\n\nポートはプロジェクトのパスから決まるので、Editor を再起動しても変わりません。ツールを呼ぶには bearer token が必要です。\n\n## 必要条件\n\n- Unity Editor 2022.3 以降。EditMode スイートは 2022.3.22f1 / 6000.0.35f1 / 6000.5.10f1 で検証しています\n- Git クライアント 2.14.0 以降を PATH に通しておいてください。Unity の Package Manager が git URL のパッケージを取得するのに使います（[Unity のマニュアル](https://docs.unity3d.com/Manual/upm-git.html)）。下の VPM リポジトリから入れる場合は要りません\n- `com.unity.nuget.newtonsoft-json` 3.2.1。依存として自動で解決されます\n- CLI に Node.js は不要です。`dotnet tool install` でインストールする場合のみ .NET SDK が必要です\n\nUnity 6.5 以降では、`instanceId` が JSON の数値ではなく文字列で返ります。64 ビットの EntityId は JavaScript の数値では正確に表せないためです。引数の `instance_id` は数値と文字列のどちらでも受け付けます。\n\n## インストール\n\nUnity の Package Manager で **Add package from git URL** を選び、次の URL を入力します。\n\n```\nhttps://github.com/isuzu-shiranui/UnityMCP.git?path=jp.shiranui-isuzu.unity-mcp\n```\n\nVCC（VRChat Creator Companion）と ALCOM では、VPM リポジトリからも入れられます。どちらもパッケージを zip でダウンロードするので、この経路に Git は要りません。\n\n```\nhttps://unity-mcp.shiranui-isuzu.dev/vpm.json\n```\n\nこの URL を貼り付ける場所は、VCC では Settings ページの Packages タブにある Add Repository です。ALCOM では「パッケージ&テンプレート」の「VPMリポジトリ」ページにある「VPMリポジトリを追加」です。追加すると、プロジェクトのパッケージ一覧に Unity MCP が並びます。ワンクリックで追加するリンクは、導入ガイドの [VCC・ALCOM をお使いの場合](https://unity-mcp.shiranui-isuzu.dev/#vpm-title) にあります。\n\nCLI をインストールします。\n\n```bash\n# Windows\nirm https://raw.githubusercontent.com/isuzu-shiranui/UnityMCP/main/install.ps1 | iex\n\n# macOS / Linux\ncurl -fsSL https://raw.githubusercontent.com/isuzu-shiranui/UnityMCP/main/install.sh | sh\n\n# .NET SDK がある場合\ndotnet tool install -g IsuzuUnityCli\n```\n\nGitHub Releases から実行ファイルを直接ダウンロードすることもできます。ファイル名は `isuzu-unity-cli-win-x64.exe` / `-osx-arm64` / `-osx-x64` / `-linux-x64` で、`SHA256SUMS` で検証できます。CLI が PATH に無い間は、Editor の Preferences > Unity MCP ページに「インストール」ボタンが出ます。\n\nインストールできたら、Claude Code / Codex 向けのスキルを導入します。\n\n```bash\nisuzu-unity-cli setup\n```\n\n## 最初のコマンド\n\nEditor がプロジェクトを開くとサーバーが起動し、descriptor ファイルを公開します。CLI はそれを読むので、ポートやトークンの指定は要りません。\n\n```bash\nisuzu-unity-cli projects                  # 起動中の Editor 一覧\nisuzu-unity-cli health                    # サーバーの状態\nisuzu-unity-cli tools                     # 利用可能なツール\nisuzu-unity-cli call play_mode_status     # ツールの実行\nisuzu-unity-cli verify                    # 再コンパイル → エラー抽出 → コンソールのエラー\n```\n\n`verify` は、スクリプトを編集したあとの再コンパイルとエラー収集を 1 回の呼び出しにまとめます。`--test` を付けるとテストも実行します。\n\nEditor が複数起動しているときは `--project <name>` で選びます。プロジェクトのディレクトリ内で実行していれば、自動で選ばれます。全コマンドは [CLI リファレンス](docs/cli.md) にあります。\n\n## MCP クライアントとの連携\n\nClaude Code の場合はこうなります。\n\n```bash\nclaude mcp add --transport http isuzu-unity http://127.0.0.1:<port>/mcp --header \"Authorization: Bearer <token>\"\n```\n\nポートは `isuzu-unity-cli doctor` の「Running Editors」に出る URL に含まれています。トークンはそこには出ません。Editor の Preferences > Unity MCP ページを開いてください。Connection の Bearer トークンの行にある「Copy」を押すとコピーできます。\n\nトークンを自分で扱いたくない場合は、CLI に登録を任せられます。\n\n```bash\nisuzu-unity-cli setup --mcp --agent claude-code\n```\n\nClaude Code はサーバーを Unity プロジェクトのパスの下に登録します。Unity プロジェクトのフォルダーで起動してください。別の場所で起動すると見えません。\n\n`--agent` は `claude-code` / `claude-desktop` / `codex` / `cursor` / `gemini` / `vscode` から選べます。\n\nClaude Desktop には拡張機能バンドルもあります。[Releases](https://github.com/isuzu-shiranui/UnityMCP/releases) の `isuzu-unity-cli.mcpb` をダブルクリックすると入ります。\n\nクライアントごとの設定、Claude Desktop 向けの stdio ブリッジ、プロトコル上の性質は [MCP クライアントの接続](docs/mcp-clients.md) にあります。\n\n## ツール\n\nEditor は最大で 88 個のツールを公開します。Timeline の 9 個と Recorder の 2 個は、`com.unity.timeline` と `com.unity.recorder` があるときだけ現れます。`test_run` と `test_results` は `com.unity.test-framework` があるときだけです。どれも入っていないプロジェクトが公開するのは 75 個のツールです。\n\n一覧と注意点は [ツール一覧](docs/tools.md) にあります。\n\n| グループ | 内容 |\n|---|---|\n| 診断 | コンソール、`Editor.log`、コンパイル状態、テスト、シーン階層、シリアライズプロパティとアセットの読み取り、Animator Controller の読み取りと問題の洗い出し、スクリーンショット、ジョブの状態 |\n| オーサリング | GameObject・コンポーネント・アセット・シーン・Prefab の作成と変更、Animator Controller のレイヤー・ステート・遷移・パラメーターの編集、メニュー実行、Play Mode の制御。GameObject 系の 8 つと `inspect_write`、`prefab_create`、`prefab_instantiate`、`animator_` の編集用 10 個は Undo 1 操作にまとまります |\n| 描画 | パイプライン・カメラ・シェーダー・マテリアルの実効値、GPU バッファとテクスチャの統計、2 枚のキャプチャの数値比較 |\n| Timeline / Recorder | トラック・クリップの検査と編集、時刻への評価、Recorder トラックの追加。該当パッケージがあるときだけ現れます |\n| ビルド | ビルド設定、プレイヤービルド、ターゲット切替 |\n| コード | リフレクションによる内部状態の読み取り、C# スニペットの実行。読み取りはプロパティの getter を呼ぶので、Unity の一部の getter はシーンを変えます |\n| 入力 | Editor の GUI 経路へのマウス・キー入力の合成と、記録・再生 |\n\nMCP の URL に `?group=diagnostics,authoring` のようにグループを付けると、`tools/list` がそのグループだけを返します。\n\n## ツールの追加\n\nEditor 側にメソッドを 1 つ書くだけです。\n\n```csharp\nusing System.Linq;\nusing UnityMCP.Editor.Core;\nusing UnityMCP.Editor.Core.Attributes;\n\ninternal static class MyTools\n{\n    [McpTool(\n        \"asset_find_by_type\",\n        \"Find project assets of a given type. Prefer a narrow type and a small limit.\",\n        Idempotency = McpIdempotency.Safe)]\n    public static string[] FindByType(\n        [McpArg(\"type\", \"Unity type name, e.g. Material.\")] string type,\n        [McpArg(\"limit\", \"Maximum paths to return.\")] int limit = 50)\n    {\n        return UnityEditor.AssetDatabase.FindAssets($\"t:{type}\")\n            .Take(limit)\n            .Select(UnityEditor.AssetDatabase.GUIDToAssetPath)\n            .ToArray();\n    }\n}\n```\n\nこれだけで `/tools` に現れ、MCP クライアントと CLI の両方から呼べます。JSON Schema はシグネチャから生成されます。\n\n`[McpTool]` の属性は 8 つあります。\n\n| プロパティ | 既定値 | 意味 |\n|---|---|---|\n| `Idempotency` | `Unsafe` | 接続失敗時に自動リトライしてよいか。読み取り専用なら `Safe` |\n| `MainThread` | `true` | Editor メインスレッドが必要か。`false` なら Editor が固まっていても応答できる（Unity API を触らないツール限定） |\n| `Destructive` | `false` | `true` なら `confirm: true` が無いと実行せず、`dry_run` に対応 |\n| `UndoGroup` | `null` | 設定すると呼び出し 1 回が Undo 1 操作にまとまる |\n| `Examples` | なし | ツールと一緒に公開する呼び出し例。モデルが引数を決める前に読みます |\n| `AlwaysLoad` | `false` | ツール検索を経ずに常に文脈へ載せます。ほぼ毎回のセッションが最初に使うツールにだけ付けてください |\n| `MaxResultSizeChars` | サーバー既定 | 大きな応答を切る位置。役に立つ部分が末尾に来るツールでは上げてください |\n| `Group` | 名前の接頭辞から | `tools/list` が絞り込みに使うグループ。接頭辞とグループが一致しないときに指定します |\n\nツール名は `^[a-z][a-z0-9_]{0,63}$` です。説明文は、モデルがそのツールを選ぶ唯一の手がかりになります。何をするかだけでなく、どういうときに使うかを書いてください。\n\nC# を書かずに、JSON ファイルでツールを追加することもできます。[定義ツール](docs/defined-tools.md) を参照してください。\n\n## 実測値\n\n3 つの経路は同じ結果を返します。ベンチマークは時間を測る前にそれを検証し、REST の `result`、MCP の `structuredContent`、CLI の標準出力が一致しなければ、1 回も計測せずに終了します。\n\n| 経路 | 1 呼び出しの p50 | 100 呼び出しあたりの Editor 側ヒープ増加 |\n|---|---|---|\n| MCP（接続を保つ） | 2.3 ms | 1.3 MB |\n| REST（接続を保つ） | 2.2 ms | 1.4 MB |\n| CLI（1 呼び出しにつき 1 プロセス） | 27.0 ms | 49 MB |\n\nCLI は 1 回の呼び出しごとにプロセスと TCP 接続を作り直します。ヒープ増加の差は、その接続ごとのバッファであって、ツールの処理ではありません。接続を保つ経路が速いのは当然で、CLI が引き換えに得ているのは、クライアントの設定も常駐プロセスも要らないことです。\n\nCLI の 1 呼び出しは、プロセスの生成から出力までで 24.0 ms でした。そのうち `Main` に入るまでが 15.8 ms です。残る 8.2 ms が、引数の解析、Editor の発見、接続、往復、出力のすべてです。Editor との往復そのものは 3.4 ms でした。`UNITY_MCP_TRACE=1` を付けると、この内訳が出ます。\n\n測定に使ったのは 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](scripts/README.md) にあります。\n\n## ドキュメント\n\n- [ツール一覧](docs/tools.md): 88 個のツールの表と注意点\n- [MCP クライアントの接続](docs/mcp-clients.md): クライアントごとの設定、Claude Desktop ブリッジ、プロトコルの性質\n- [CLI リファレンス](docs/cli.md): 全コマンド、プロジェクトの選択、終了コード、マシン上に置くもの\n- [定義ツール](docs/defined-tools.md): JSON ファイルで `probe` / `script` / `sequence` ツールを追加する\n- [Editor 入力の合成・記録・再生](docs/input-tools.md): `input_pointer` / `input_key` / `input_record` / `input_replay`\n- [アーキテクチャ](docs/architecture.md): 経路図、Editor 側のクラス、設定、テスト\n- [トラブルシューティング](docs/troubleshooting.md)\n- [セキュリティ](docs/security.md)\n- [v3 からの移行](docs/migration-v3.md)\n- [CHANGELOG](jp.shiranui-isuzu.unity-mcp/CHANGELOG.md)\n\n## セキュリティ\n\n- サーバーは `127.0.0.1` にだけバインドします。`OPTIONS` を除く全リクエストに bearer token が必要です。`OPTIONS` は CORS のプリフライトで、本文のない 204 を返すだけです\n- descriptor ファイルとトークンファイルは資格情報として扱ってください。これらを読めれば、Editor 内でコードを実行できます\n- プレイヤービルドには、Development Build を含めて一切入りません。ソースはすべて `Editor/` 配下にあり、アセンブリ定義が Editor 限定です。CI が毎回検査します\n\n詳細は [セキュリティ](docs/security.md) にあります。\n\n## ライセンス\n\nMIT\n",
  "bytes": 8815,
  "sha": "313548b717fd9ca7fd00e796a16bbc3f347aac90b5e2a48b872954079ac29aff",
  "repo_slug": "isuzu-shiranui/unitymcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_isuzu_shiranui_unity_mcp_1e381e35/readme"
}