MCP for Unity を入れた直後の動作検証フローと、踏んだ 3 つのハマりどころ

新規 Unity プロジェクト (AtmoTest、Unity 6.0 URP 2D テンプレ) に MCP for Unity 9.6.8 (com.coplaydev.unity-mcp) を入れた直後、Claude Code から Editor 操作が本当に通るかを最小スモークテストで確認した。Cube + Rigidbody で物理を動かし、Play モードを往復させる 1 分の検証フローと、その中で踏んだ 3 つのハマりどころを残しておく。

前提

• Unity Editor は 開いたまま にしておく。MCP for Unity のサーバは Editor プロセスに同梱される uvx --from "mcpforunityserver==X" mcp-for-unity プロセスとして起動するので、Editor を閉じると即切断する。
• HTTP transport (デフォルト) はローカル 127.0.0.1:8080 で待ち受ける。
• 2D テンプレ (URP 2D) でも 3D primitive (Cube 等) は配置できる。スモークテストで物理を確認するなら 3D Cube + Rigidbody が一番速い。

「サーバは生きているのにツールが出ない」を疑う 4 ステップ

claude セッションを開いたが mcp__UnityMCP__* ツールがツール一覧に見当たらない、というときの確定診断手順。これが一番ハマりやすいので最初に書く。

1. 登録確認

claude mcp get UnityMCP

Status: ✓ Connected を確認。✗ Not connected なら設定側 (.mcp.json のパス、コマンド) の問題。

2. サーバ生存確認

lsof -iTCP:8080 -sTCP:LISTEN

Python (uvx) プロセスが LISTEN していれば Editor 側 MCP サーバは正常稼働。何も出ないなら Editor 側で MCP for Unity の起動に失敗している (Editor の Console を見る、または Editor を再起動)。

3. HTTP 直叩き

curl で JSON-RPC initialize → tools/list を直接叩く。レスポンスに 43 件前後のツール定義が並んでいれば、サーバは健全。Claude Code 側に渡すための JSON-RPC スキーマもこの段で確認できる。

4. Claude Code 側のロード

ここまで通っていてツール一覧に出ないなら、現セッションが起動時に MCP ツール定義をロードしていないだけ。Claude Code を再起動 すると次セッションから mcp__UnityMCP__* がツール一覧に並ぶ。

要は「サーバは生きているのにツールが使えない」状況は Claude Code 側のセッション初期化のタイミング問題なので、3 まで通ったら迷わず再起動でよい。今回のケースもこのパターンで、再起動後に正常化した。

1 分スモークテスト

新規プロジェクトで MCP for Unity を入れた直後の最小検証セット。

1. manage_scene(action=get_active) で現在シーンを取得 (SampleScene などが返ればアタッチ成功)。
2. read_console(types=["error","warning"]) で MCP セットアップ系のログ以外にエラーが出ていないことを確認。
3. manage_material(action=create, material_path="Assets/RedTest.mat", color=[1,0,0,1]) で赤マテリアルを作る。
4. manage_gameobject(action=create, name="TestCube", primitive_type="Cube", position=[0,5,0]) で 3D Cube を生成。返ってくる instanceID を控える。
5. manage_components(action=add, target=<instanceID>, component_type="Rigidbody", properties={"useGravity": true, "mass": 1}) で物理付与。
6. manage_editor(action=play) → 数秒待機 → manage_editor(action=stop) で Play モード往復。
7. read_console(types=["error","warning"]) で Play モード中にエラーが出ていないことを確認。
8. 後片付け: manage_gameobject(action=delete, target=<instanceID>, search_method=by_id) + manage_asset(action=delete, path="Assets/RedTest.mat")。シーンを保存しなければ SampleScene は dirty 扱いだが、Editor を閉じれば破棄される。

成功条件は「Play モード中の error/warning が 0 件 + Cube が生成された + Rigidbody が付いた」。AtmoTest では全項目 PASS した。これが 1 分で通れば、MCP for Unity の主要ツール (manage_scene / manage_gameobject / manage_components / manage_material / manage_editor / read_console) は使える状態と判断してよい。

ハマりどころ 3 つ

1. manage_material(create) は親フォルダがないと黙ってコケる

Assets/Materials/RedTest.mat のように途中フォルダが存在しないパスを渡すと:

Creating asset at path Assets/Materials/RedTest.mat failed.

の形で AssetDatabase.CreateAsset が黙って失敗する。エラーが出るとはいえ何が原因かは伝わらない。

回避策は 2 つ。検証用の使い捨てマテリアルなら Assets/RedTest.mat のように 既存フォルダ (Assets/ 直下) に置けば通る。本番のマテリアルを切る場合は manage_asset(action=create_folder, path="Assets/Materials") を先に呼んでから manage_material(create) を続ける。

2. Play モード遷移と並列で renderer 操作を投げると instanceID が解決できない

manage_material(assign_material_to_renderer, target=-20002) と manage_editor(action=play) を 同じバッチで並列 に投げると、Play モード突入のドメインリロードでタイミング差が生まれ、material 側のリクエストが:

Could not find target GameObject: -20002

でこける。Play モード遷移を含むツール呼び出しは 逐次 に並べる (Play 前に renderer 操作を完了させる)。

並列が効くのは「Editor がアイドル状態 + ドメインリロードを跨がない」操作だけ、と覚えておく。Play / Stop / Recompile / AssetDatabase.Refresh のような状態遷移を含む呼び出しは、その前後の操作と直列化する。

3. editor_state リソース URI は推測で当たらない

mcpforunity://editor_state を直接読みに行くと:

Resource not found: Unknown resource

が返る。実際の URI は別形式 (リソース一覧に出てくる名前) なので、新環境では先に ListMcpResourcesTool(server="UnityMCP") でリソース一覧を取って正しい URI を確認する。

そもそも Editor 状態の取得だけなら manage_scene(get_active) と read_console(get) を組み合わせるほうが確実。リソース URI は MCP server のバージョンで変わる可能性があるので、ツール経由で済むことはツール経由で済ませる。

導入時のリポ差分

Packages/manifest.json に com.coplaydev.unity-mcp を追加すると、付随して Packages/packages-lock.json と ProjectSettings/ShaderGraphSettings.asset も書き換わる。AtmoTest では 3 ファイル合計 19 行 insert のみで済んだ。

 "dependencies": {
+  "com.coplaydev.unity-mcp": "https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main",
   "com.unity.collab-proxy": "...",

ShaderGraphSettings.asset の差分は MCP for Unity が触るものではなく、Editor 起動時に URP 側が書き直す副作用なので一緒にコミットしてよい。

なぜここで効くか

MCP for Unity は「Claude Code から Unity Editor を直接叩ける」非常に強力なツールだが、初回導入直後は 4 つの層 (Claude Code セッション、.mcp.json 設定、Editor プロセス内 MCP サーバ、HTTP transport) のどこで詰まっているかが見えにくい。claude mcp get → lsof → curl → 再起動の 4 ステップで層を特定する習慣をつけると、「ツールが出ない」を 5 分以内に切り分けられる。スモークテストの 1 分セットも、新規プロジェクトでの「とりあえず動くことを確認する」ベースラインとして使える。

(Origin: 2026-05-09、AtmoTest プロジェクトに MCP for Unity 9.6.8 を導入した直後の検証セッション。3 ファイル diff を chore: add MCP for Unity 9.6.8 package でコミット & push (49030e0..3e1050e)。検証時バージョン: MCP for Unity Editor 9.6.8 / mcp-for-unity-server v3.2.4。公式 setup problems: https://github.com/CoplayDev/unity-mcp/wiki/3.-Common-Setup-Problems 。)