🤖

Unity × Claude Code でTDDの環境構築 MCP導入ガイド

2025/07/09に公開

Unity

TDD

Model Context Protocol

Claude Code

tech

!本記事は WSL 経由で Unity MCP を使うという記事でした。

が、記事を書いた3日後に Claude Code がネイティブ Windows に対応しました。
もはや、この記事の存在意義は薄いのですが、

何らかの理由で WSL 経由で使いたい人のために、この記事は残しておきます

 環境Unity 6000.2.0b8
新機能の調査でこの時β版を使ってたんですが、LTSでも以下の手順で動くと思います。多分…。

Test Framework 1.5.1
Unity MCP 1.1.1

 TL;DRClaude Code と Unity でテストを書く時、初期設定では手動でUnity Editorからテストの実行・結果確認を行う必要がありました
効率化するため、Claude CodeとUnity MCPを組み合わせた環境を構築しました
MCP の設定を行うことで、自律的にテスト実行・修正まで行ってくれるようになり、より Claude Code にまかせっきりに出来るようになりました
これでようやく、テストコードを書く時の体験が Web の開発に並びました

 はじめに：Unity x Claude Code で TDD は困難UnityのTDDは、AIによるコーディングと相性がよくありませんでした。

 課題
テスト実行の手間: Unity Editor内での操作が必要

CLI実行の制限: Unity起動中はMultiple Unity instances cannot open the same projectエラーが発生

結果確認の煩雑さ: Test Runnerウィンドウでの視覚的確認が必要

失敗テスト分析: 個別にログを確認する必要
とにかく、手動で実行してから、結果をAIにコピペするということが、とても手間でした。

 理想的なTDD環境これを目標にしました。

コマンド一発でテスト実行

即座の結果表示と失敗原因分析
人の手を介さないAIによるタスク遂行
色々試した結果、Model Context Protocol (MCP) を使うことがベストという結論に至りました。

 Unity CLI実行の根本的問題ちょっとだけ脱線します。

「MCPなんか使わずとも、CLIで テスト結果を取得すればいいのでは？」

と思う方も居るでしょう。
私だって最初はそう思っていました。

では、なぜそうしなかったのかという話です。

 Multiple Unity Instances エラーUnity開発者なら誰もが経験する問題：Unity Editorでプロジェクトを開いている状態でCLI経由でのテスト実行を試みると、以下のエラーが発生します。
Unity.exe -runTests -projectPath ./MyProject -testResults ./results.xml
# → "Multiple Unity instances cannot open the same project"

 この問題の技術的背景この制限は、Unityのプロジェクトファイルロック機構によるものです：

プロジェクトの排他制御: 同一プロジェクトに対する複数インスタンスの起動を防止

データ整合性の保護: アセットやシーンファイルの競合状態を回避

開発中の制約: 一般的な開発状況（Unity Editor起動中）でのCLI自動化を阻害

 この問題の回避策、とその問題点

回避策
問題点


Unity Editorを毎回閉じる
開発効率の大幅低下、ワークフロー断絶

別プロジェクトコピーでの実行
環境差異の発生リスク、同期コスト

つまり、Unity は Edior を起動しながら、CLI でテストを実行ということが出来ません。

また、Editor を起動していないと、コードの自動コンパイルも走りません。
ここまで調べて、CLI はあきらめることにしました。

 ソリューション：Unity MCP + Claude Codeそこで、Unity MCPを使うことにしました[1]。

 技術選択の理由このようなメリットがあります。


従来手法
問題
MCP の利点


CLI実行
Multiple Unity instances エラー
Unity Editor内で実行

手動操作
効率が悪い
Claude Code が必要に応じて実行

バッチ処理
リアルタイム性がない
即座に結果取得


 アーキテクチャ概要今回、Windows の環境で構築しました。
Claude Code は WSL の環境でしか動かないため、

Windows 側で動いている Unity と通信するためには、一工夫が必要です。
全体像はこのようになります。
(↑図はAIに書いてもらいました。便利ですね)

 MCP方式による根本解決Unity Editor内のWebSocketサーバー経由でテスト実行するため：
新しいUnityインスタンスを起動しない
プロジェクトロック制限を回避
開発中でも安定したテスト自動化が可能

 環境構築ガイド
 Phase 1: 基盤環境の準備基本的には、MCPのドキュメントに従って構築します。

ドキュメント通りの部分は、非常に簡略な説明に留めます。

 WSL + Claude Code環境# Node.js環境の確認
node --version  # v18以上必要
npm --version   # v9以上必要

 Phase 2: Unity MCP Server導入Unity Package Managerから導入：
Unity Package Manager -> Add package from git URL..

で、次の URL を入力
https://github.com/CoderGamester/mcp-unity.git
!重要: プロジェクトパスにスペースが含まれていると、MCP接続が失敗します。

✅ D:/source/repos/kaibutsu-baseball

❌ D:/source/repos/kaibutsu baseball
導入後の自動設定:
WebSocketサーバー（ポート8090）が起動
MCP設定ファイルが自動生成
Node.js MCPクライアントがビルド

 Phase 3: Claude Code設定WSL環境特有の設定が必要です：
WSL側に作られている Claude Code の設定を編集します。

ドキュメント通りに書くと動かないので、次のように内容を変更します。
~/.claude.json
{
  ...
  "mcpServers": {
    "mcp-unity": {
      "command": "/mnt/c/Windows/System32/cmd.exe",
      "args": [
        "/c",
        "cd /d C:\\[your-repository-path]\\LibraryLibrary\\PackageCache\\com.gamelovers.mcp-unity@71e48418770f\\Server~ && node build/index.js"
      ]
    }
  },
  ...
}
!WSL特有の注意点: シンプルなnodeコマンドではなく、Windows cmd.exe経由での実行が必要。これにより、Windows上のUnity WebSocketサーバーとの接続が可能になります。

 Phase 4: 接続確認Unity Editor内で：
Tools > MCP Unity > Server Window

Start Serverをクリック

Status: Server Onlineを確認
Claude Code起動後：
/mcp コマンド
一覧の中から mcp-unity を選択
以下のようになっていれば接続成功です
Status: ✔ connected
Tools: 9 tools
Capabilities: tools · resources · prompts

 TDD実践例
 基本的なテスト実行Unity で実行可能なテストの一覧を表示してください
実行結果例:
EditMode Tests: 45/48 passed

失敗テスト:
- MotionCaptureDataConverterTest.ConvertMotionCaptureTimestampToISO8601
- PicherAppearanceResultTest.BallDataTest.ConstructorAndExport
- PitchingInitialDataTest.PitchingInitialData_コンストラクタでプロパティが正しく設定される
こんな感じで、一発で結果を取得してくれるようになります。

 開発効率の向上Before（従来の手動TDD）:
Unity Editor → Test Runner → 実行ボタン
結果確認とログチェック → 結果をClaude Code にコピーして渡す
コード修正
再テスト実行 → 結果をClaude Code にコピーして渡す
と、何度も人の手を介さないとできなかったものが
After（AI支援TDD）:
テスト実装の指示
自動テスト実行と結果表示
AI修正提案の適用
自動再テスト
のように、自動でAIが結果を見てくれるようになります。

 トラブルシューティング実録
 Unity起動中のCLI実行問題症状: Multiple Unity instances cannot open the same project
問題の詳細:

Unity Editorでプロジェクトを開いている状態で、CLI経由でのテスト実行を試みると、Unityの仕様によりエラーになってしまう。
従来の回避策とその問題点:

CLIを使ってテスト実行を行わない！

 PlayModeテストの接続エラー症状: Error: Connection closed
原因: Unity のドメインリロードによるWebSocket接続切断
解決策:
Edit > Project Settings > Editor > "Enter Play Mode Settings"
→ "Reload Domain" をOFF

 WSL環境での接続タイムアウトドキュメント通りに行うと、WSL 環境だとこの問題に突き当たると思います
症状: Connection timeout
原因: WSL内でのNode.js直接実行
解決策: Windows cmd.exe経由での実行に変更

 まとめ：TDDの新時代以上のアプローチにより、Unity x ClaudeCode で TDD を行う時の精神的なハードルが大きく下がりました。

これまでは、ClaudeCode の恩恵をフルで受け切れていない感じがしていたのですが、これで AI のスピード感を余すことなくプロダクトの開発に乗せられるようになった気がします。

 その他.claude.json において、思いっきりリポジトリを設定ファイルに書いています。

これ、書かなくていい方法をご存じの方いらっしゃいましたら、コメントで教えてください
~/.claude.json
{
  ...
  "mcpServers": {
    "mcp-unity": {
      "command": "/mnt/c/Windows/System32/cmd.exe",
      "args": [
        "/c",
        "cd /d C:\\[your-repository-path]\\Library\\PackageCache\\com.gamelovers.mcp-unity@71e48418770f\\Server~ && node build/index.js"
      ]
    }
  },
  ...
}

 参考資料Unity MCP GitHub
Unity Test Framework

脚注
一番人気な Unity の MCP はjustinpbarnett氏が作ったものなのですが、これはテストの実行コマンドがなかったので、採用を見送りました ↩︎

回避策	問題点
Unity Editorを毎回閉じる	開発効率の大幅低下、ワークフロー断絶
別プロジェクトコピーでの実行	環境差異の発生リスク、同期コスト

従来手法	問題	MCP の利点
CLI実行	Multiple Unity instances エラー	Unity Editor内で実行
手動操作	効率が悪い	Claude Code が必要に応じて実行
バッチ処理	リアルタイム性がない	即座に結果取得

環境

TL;DR

はじめに：Unity x Claude Code で TDD は困難

課題

理想的なTDD環境

Unity CLI実行の根本的問題

Multiple Unity Instances エラー

この問題の技術的背景

この問題の回避策、とその問題点

ソリューション：Unity MCP + Claude Code

技術選択の理由

アーキテクチャ概要

MCP方式による根本解決

環境構築ガイド

Phase 1: 基盤環境の準備

WSL + Claude Code環境

Phase 2: Unity MCP Server導入

Phase 3: Claude Code設定

Phase 4: 接続確認

TDD実践例

基本的なテスト実行

開発効率の向上

トラブルシューティング実録

Unity起動中のCLI実行問題

PlayModeテストの接続エラー

WSL環境での接続タイムアウト

まとめ：TDDの新時代

その他

参考資料

Discussion