Unityでつくる 横スクロールシューティング

ダークモード

Claude Code × Unity MCP 連携手順 ​

このページは、教材準備のために Claude Code から Unity エディタを操作できるようにする 手順です。シーン雛形作り、エラー調査、手順書の検証、スクリーンショット撮影などの準備作業を効率化する目的で使います。

生徒の授業では使いません

この連携は 先生・教材作成者の準備作業用 です。生徒の授業では使わない前提で書いています。生徒は教材の手順どおり、自分の手で Unity を操作してください。

これは何か ​

  • MCP（Model Context Protocol） は、AI アシスタントが外部のツールやアプリを操作するための共通の仕組みです
  • CoplayDev/unity-mcp（MCP for Unity）を Unity に入れると、Claude Code が MCP 経由で Unity エディタを操作できるようになります。GameObject の作成・編集、スクリプトの作成、Console の読み取り、シーンの保存などが可能です
  • MIT ライセンスの無料 OSS です。Unity Technologies の公式製品ではありません
  • 対応バージョンは Unity 2021.3 〜 6.x です
  • ドキュメント: https://coplaydev.github.io/unity-mcp
  • GitHub: https://github.com/CoplayDev/unity-mcp

ツールは変化が速い

MCP for Unity は活発に開発されており、メニュー名・ツール名・手順が変わることがあります。このページと食い違う場合は、最新の README とドキュメントを優先 してください。

必要なもの ​

もの入れ方確認コマンド
Unity 6Unity Hub からインストール—
Claude Codecurl -fsSL https://claude.ai/install.sh | bashclaude --version
Python 3.10 以上macOS は brew install python などpython3 --version
uv（Python のパッケージ管理ツール）macOS: brew install uv または curl -LsSf https://astral.sh/uv/install.sh | shuv --version
gitmacOS は Xcode Command Line Tools（xcode-select --install）などgit --version
bash
# まとめて確認
claude --version
python3 --version
uv --version
git --version

Windows の場合

Claude Code、uv にはそれぞれ Windows 用のインストール方法があります。各公式ドキュメントを参照してください。以下の手順は macOS を前提に書いています。

1. Unity 側: MCP for Unity パッケージを入れる ​

  1. 教材用の Unity プロジェクト（SpaceShooter）を開く

  2. Window > Package Manager を開く

  3. 左上の + ボタン → Add package from git URL... を選ぶ

  4. 次の URL を入力して Add を押す

    text
    https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main

  5. インポートが終わると セットアップウィザード が開く。Python と uv が検出されていることを確認して Done を押す

安定版に固定したい場合

#main は最新の開発版です。教材準備中に挙動が変わると困る場合は、リリースタグを指定して固定します（例: #v10.0.0。実在するタグ名は GitHub の Releases で確認してください）。

text
https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#v10.0.0

2. Claude Code 側: MCP サーバーを登録する ​

自動設定（おすすめ） ​

  1. Unity で Window > MCP for Unity を開く
  2. クライアント一覧から Claude Code を選ぶ
  3. Configure Selected（バージョンによっては Register）を押す

手動設定 ​

自動設定がうまくいかない場合は、ターミナルで登録します。

HTTP トランスポートの場合（ポートは MCP for Unity ウィンドウに表示されている番号に合わせる）

bash
claude mcp add --transport http unityMCP http://localhost:8080/mcp

stdio トランスポートの場合

bash
claude mcp add unityMCP -- uvx --from mcpforunityserver mcp-for-unity --transport stdio

プロジェクト単位で共有する ​

--scope project を付けると、設定がプロジェクト直下の .mcp.json に保存されます。リポジトリにコミットすれば、ほかの先生とも同じ設定を共有できます。

bash
claude mcp add --scope project --transport http unityMCP http://localhost:8080/mcp

WARNING

トランスポート（HTTP / stdio）を切り替えたら、Claude Code を 再起動 してください。

3. 接続を確認する ​

  1. Unity の Window > MCP for Unity でステータスが Connected になっていることを確認する

  2. ターミナルで登録を確認する

    bash
    claude mcp list

  3. プロジェクトのフォルダで Claude Code を起動し、/mcp と入力して unityMCP が接続済みで、ツールが一覧に出ていることを確認する

  4. 試しに次のように頼んでみる

    text
    シーンに赤・青・黄色の Cube を横に並べて作って
    text
    Unity の Console のエラーを読んで、内容を教えて

Unity の Scene ビューに Cube が現れれば成功です。確認したら Cube は消しておきます（Ctrl+Z / Cmd+Z でも戻せます）。

4. 教材準備での使い方の例 ​

教材の手順書（docs/lessons/）や仕様（spec/LESSON_SPEC.md）を Claude Code に読ませたうえで頼むと、精度が上がります。

目的プロンプト例
手順書の検証「docs/lessons/07-enemy.md の手順どおりに Enemy_Straight プレハブを作って。手順と実際の Unity の画面で食い違うところがあったら報告して」
シーン雛形作り「第11回を始める時点のシーンを作って。spec/LESSON_SPEC.md のヒエラルキーのうち、第10回までに出てくるものだけを配置して」
エラー調査「Console のエラーを要約して、原因のスクリプトを直して。直した箇所を教えて」
コードの検証「docs/appendix/scripts.md の PlayerShooter を Assets/_Game/Scripts/ に作ってコンパイルが通るか確認して」
設定の確認「Enemy_Straight プレハブの Rigidbody と Collider の設定が仕様（Is Kinematic ON、Use Gravity OFF、Is Trigger ON）どおりか確認して」
スクリーンショット「Game ビューのスクリーンショットを撮って docs/public/images/lesson07-01.png に保存して」
数値の調整「▶ で動かして、敵の出現間隔 1.5 秒が難しすぎないか見て。Console に出たログも教えて」
一括作業「Assets/_Game/Prefabs のプレハブをすべて調べて、Tag と Collider の一覧を表にして」

スクリーンショット機能について

スクリーンショットや Play モードの操作ができるかどうかは、MCP for Unity のバージョンによって異なります。/mcp で表示されるツール一覧で、対応するツールがあるか確認してください。ない場合は、Unity の Window > General > Recorder や OS のスクリーンショット機能を使います。

5. 使うときの注意 ​

  • 元に戻せる状態で使う: Claude が加える変更は大きくなることがあります。プロジェクトを git で管理し、こまめにコミット してから頼みましょう。Unity の Undo（Ctrl+Z / Cmd+Z）でも戻せますが、ファイルの作成・削除は戻らないことがあります
  • Unity を Finder や Unity Hub から起動すると PATH が通らない: macOS では、Dock や Finder から起動したアプリはシェルの PATH を引き継がないため、Unity から claude や uv が見つからないことがあります。次のどちらかで対処します
    • ターミナルから Unity Hub を起動する（例: open -a "Unity Hub"）
    • MCP for Unity ウィンドウの Choose Claude Install Location で claude の場所を指定する（which claude で確認できます）
  • トランスポートを切り替えたら Claude Code を再起動 する
  • ツールは変わりやすい: 不具合や手順の違いがあれば、まず最新の README を確認する
  • 生成物は必ず人が確認する: 手順書の検証に使う場合でも、最終的には先生自身が生徒と同じ手順で操作して確認してください。Claude がコードで直接作った状態と、生徒がメニューから手で作った状態は細部が異なることがあります

6. トラブルシューティング ​

症状原因対処
パッケージ追加時に git のエラーが出る（No 'git' executable was found など）git が入っていない、または Unity から見えていないgit --version で確認。入れたあと Unity Hub と Unity を再起動。それでもだめならターミナルから Unity Hub を起動する
ステータスが Connected にならないサーバーが起動していない、設定が古いMCP for Unity ウィンドウでサーバーを再起動／Configure Selected をやり直す。Claude Code も再起動する
uv が見つからないuv 未インストール、または PATH が通っていないuv --version で確認。which uv の結果をウィンドウで指定するか、ターミナルから Unity Hub を起動する
claude が見つからないPATH が通っていないChoose Claude Install Location で指定。which claude で場所を確認
ポートが使用中（address already in use）別のプロセスや別の Unity が同じポートを使っているlsof -i :8080 で使っているプロセスを確認して終了するか、ウィンドウでポートを変え、claude mcp add の URL も合わせる
/mcp に unityMCP が出ない登録したスコープ・フォルダがちがうclaude mcp list で確認。--scope project の場合は、そのプロジェクトのフォルダで Claude Code を起動する
ツールを呼ぶとタイムアウトするUnity がコンパイル中・インポート中、またはモーダルダイアログが開いているUnity の画面を確認し、ダイアログを閉じる。コンパイル完了を待ってから再実行
複数の Unity を開いていて意図しない方が操作される複数インスタンスの接続作業する Unity だけを開く。ドキュメントのマルチインスタンスの項を参照
アップデート後に動かなくなったパッケージとサーバーのバージョン不一致Package Manager でパッケージを更新し、ウィンドウから再設定。安定版タグへの固定も検討