mcp-unity：MCPサーバー 作り方でUnity開発をClaude・CursorのAIと直接連携するプラグイン

この記事ではMCPに特化して解説します。MCP（Model Context Protocol）全般は MCPサーバーの作り方2026完全ガイド をご覧ください。

Unity開発にMCPをつなぐとどうなるか

Model Context Protocol（MCP）は、AIアシスタントが外部ツールやデータソースと標準化された方法で通信するためのプロトコルです。このプロトコルをUnity Editorに接続したのが mcp-unity です。GitHubで1,600以上のスターを集め、Cursor・Claude Code・Codex CLI・Windsurf・GitHub Copilot・Google Antigravityといった主要なAI統合IDEすべてに対応した、ゲーム開発向けMCPサーバーの実装です。

従来のゲーム開発ワークフローでは、コードをIDEで書いてUnity Editorに切り替えて確認し、エラーがあればまたIDEに戻るという往復が頻繁に発生していました。mcp-unityはこの往復を根本的に削減します。CursorやClaude Codeから「Playerオブジェクトにリジッドボディコンポーネントを追加して、質量を5に設定して」と指示すると、AIがUnity内のGameObjectを直接操作します。結果のコンソールログもIDEにリアルタイムで返ってくるため、エラー確認のためにUnity Editorを手動で開く必要がありません。

このツールの仕組みは、Unity側のC#プラグインとNode.jsで実装されたMCPサーバーの2層構造です。C#プラグインがUnity Editorと通信し、Node.jsサーバーがMCPプロトコルを実装してAIアシスタントとのブリッジを担います。通信はWebSocketまたは標準I/Oを経由します。

アーキテクチャ：2層構造の詳細

mcp-unityのアーキテクチャは、MCPクライアント（AI IDE）、Node.jsサーバー、Unity Editorの3つのコンポーネントが連携する設計です。

Node.jsサーバー層

Server/src/index.ts に実装されたMCPサーバーは、AIアシスタントからのツール呼び出しリクエストを受け取り、Unity Editorとの通信に変換します。TypeScriptで記述されており、Zodスキーマによる入出力バリデーションが組み込まれています。

Unity C#プラグイン層

McpUnityServer.cs がUnity EditorとNode.jsサーバーの橋渡しをします。Unity Package Manager経由でプロジェクトに追加され、Tools > MCP Unity > Server Window から起動・設定できます。WebSocketサーバーをポート8090（変更可能）で起動し、Node.jsからのリクエストを受け付けます。

ツールとリソースの体系

mcp-unityが提供するMCPツールは30種類以上あります。主なカテゴリは以下の通りです。

MCPリソースとして公開されているのは unity://menu-items、unity://scenes-hierarchy、unity://gameobject/{id}、unity://logs、unity://packages、unity://assets、unity://tests/{testMode} です。AIはこれらのリソースを読み取って、Unityプロジェクトの現在の状態を把握した上で操作を行います。

インストールとセットアップ手順

mcp-unityのセットアップは3つのステップで構成されます。Node.jsのインストール、Unity Package Managerへの追加、AI IDEへの設定追加です。

ステップ1：Node.js 18以上をインストール

macOSでHomebrewを使う場合：

brew install node@18
node --version  # v18.x.x 以上であることを確認

Windowsの場合は nodejs.org からLTS版インストーラーをダウンロードして実行します。

ステップ2：Unity Package Managerで追加

1. Unity Editorを開く
2. Window > Package Manager を開く
3. 左上の + ボタンをクリック
4. Add package from git URL... を選択
5. 以下のURLを入力して Add をクリック

https://github.com/CoderGamester/mcp-unity.git

インストール後、Tools > MCP Unity > Server Window を開き、Start Server ボタンをクリックしてWebSocketサーバーを起動します。

ステップ3：AI IDEへの設定追加

Cursor・Claude Code・Windsurf・GitHub Copilotなど、JSON設定ファイルを使うIDEでは以下の設定を追加します。ABSOLUTE/PATH/TO の部分は実際のインストールパスに置き換えてください。

{
  "mcpServers": {
    "mcp-unity": {
      "command": "node",
      "args": [
        "ABSOLUTE/PATH/TO/mcp-unity/Server~/build/index.js"
      ]
    }
  }
}

Unity Editorの Tools > MCP Unity > Server Window から Configure ボタンをクリックすることで、このJSON設定を自動生成することもできます。

Codex CLI（~/.codex/config.toml）の場合：

[mcp_servers.mcp-unity]
command = "node"
args = ["ABSOLUTE/PATH/TO/mcp-unity/Server~/build/index.js"]

WebSocketポートの変更（オプション）

デフォルトのWebSocketポートは8090です。変更する場合：

# Unityの環境変数でポートを設定（Windowsの例）
set UNITY_PORT=9090

または Tools > MCP Unity > Server Window のWebSocket Port欄で変更してから Restart Server を実行します。

実践的なユースケース

ユースケース1：GameObjectの一括セットアップ

敵キャラクター10体を一度に配置する操作を batch_execute ツールで実現できます。

AIへの指示例：

Enemy_1からEnemy_10という名前のGameObjectを10個作成して、
それぞれにRigidbodyコンポーネントを追加し、massを1.5に設定して。
すべてEnemiesという親オブジェクトの下に配置して。

batch_executeツールが複数の update_gameobject と update_component 操作を一括実行し、失敗した場合のロールバックも行います。

ユースケース2：テストの自動実行とエラー修正

EditModeのテストをすべて実行して、失敗したテストがあればコンソールログを確認して修正案を提案して。

run_tests ツールでUnity Test Runnerを起動し、get_console_logs でエラーを取得してAIが分析します。Reload Domainが有効な場合、Play Modeテストでは Edit > Project Settings > Editor > Enter Play Mode Settings から Reload Domain をオフにする必要があります。

ユースケース3：マテリアルの一括作成と適用

URP Litシェーダーを使った赤いマテリアル「EnemyMaterial」を作成して、
Enemyという名前のすべてのGameObjectに適用して。

create_material で新規マテリアルを作成し、assign_material で各GameObjectのRenderer componentに適用します。

ユースケース4：プレハブからのシーン構築

PlayerControllerスクリプトを使ったPlayerプレハブを作成して、
Level1という名前のシーンにそのプレハブを配置して、
位置を(0, 1, 0)に設定してから保存して。

create_prefab、create_scene、add_asset_to_scene、move_gameobject、save_scene の一連の操作をAIが自動でオーケストレーションします。

ユースケース5：プロジェクト構造の把握と最適化

unity://assets リソースを確認して、重複しているテクスチャアセットがないか調べて。
unity://packages を確認して、更新が必要なパッケージがあれば教えて。

MCPリソースを使ってプロジェクトの現状を把握し、改善点を提案します。

競合・代替ツールとの比較

mcp-unityの最大の差別化ポイントは、標準化されたMCPプロトコルを採用することで、複数のAI IDEから統一した方法でUnity Editorを操作できる点です。

Unity 6.2では公式のAI機能（旧Unity Museを含む）が組み込まれる予定ですが、そちらはUnity Editor内のコンテンツ生成（テクスチャ・アニメーション・スプライト生成）とAPIドキュメント参照に特化しています。mcp-unityはEditor操作の自動化と外部AI IDEとの連携に強みがあり、補完的な関係として共存します。

Unity 6.2のAI機能との具体的な違い：

• mcp-unity：「Player GameObjectのタグをEnemyに変更して」「iOS向けビルドを実行してエラーを修正して」のようなEditor操作・自動化に強い
• Unity 6.2 AI：「このキャラクターのウォーキングアニメーションを生成して」「このマテリアルにSFテクスチャを生成して」のようなコンテンツ生成に強い

カスタムツールの追加方法

mcp-unityはプロジェクト固有のワークフローに合わせたカスタムツールを追加できます。

Unity側（C#）でカスタムツールを追加する場合：

// Unity側: McpToolBase を継承したカスタムツール例
public class MyCustomTool : McpToolBase
{
    public override string Name => "my_custom_tool";
    
    public override async Task<string> ExecuteAsync(JObject parameters)
    {
        // プロジェクト固有の処理を実装
        string assetPath = parameters["asset_path"]?.ToString();
        // カスタムアセット処理...
        return JsonConvert.SerializeObject(new { success = true });
    }
}

Node.js側（TypeScript）でツールハンドラーを追加：

// Server/src/tools/myCustomTool.ts
import { z } from 'zod';
import { McpToolHandler } from '../types';

export const myCustomToolSchema = z.object({
  asset_path: z.string().describe('Path to the asset'),
});

export const myCustomToolHandler: McpToolHandler = async (params, unityConnection) => {
  const { asset_path } = myCustomToolSchema.parse(params);
  return await unityConnection.sendRequest('my_custom_tool', { asset_path });
};

よくある質問・つまずきポイント

Unity 6とUnity 2021 LTSの互換性

過去のREADMEではUnity 2021 LTS以上と記載されていましたが、現在のREADMEではUnity 6以上が推奨されています。古いUnityバージョンでの動作は保証されていないため、Unity 6への移行を検討してください。

セキュリティ上の注意点

mcp-unityはローカルのWebSocketサーバーを起動します。本番環境やリモートアクセス可能な環境での運用は、セキュリティ上のリスクを十分に検討した上で行ってください。特に execute_menu_item ツールはUnityのすべてのメニュー項目を実行できるため、AIへのアクセス権限を適切に管理することが重要です。

mcp-unityを使ったチーム開発ワークフロー

mcp-unityは個人開発だけでなく、チーム開発での活用にも適した設計になっています。

コードレビューの効率化

AIアシスタントがUnityプロジェクトのコンテキストを把握した状態でコードレビューを支援できます。unity://scenes-hierarchy と unity://assets リソースを使って、プロジェクト全体の構成を把握した上でコードの問題点を指摘できます。

# Claude Codeにmcp-unityを通じてプロジェクト全体をレビューさせる例
# プロンプト例：
# "unity://assets を確認して、
#  使われていないアセットと重複しているスクリプトを見つけて一覧にして"

オンボーディングの加速

新しいチームメンバーがプロジェクトに参加した際、mcp-unityとAIアシスタントを組み合わせることで、プロジェクト構造の理解を加速できます。

AIアシスタントへの指示例：
"unity://scenes-hierarchy を読んで、このプロジェクトのシーン構造を
日本語で説明してください。特にゲームの進行フローに関連するシーンの
繋がりを重点的に解説してください"

自動化スクリプトの品質管理

run_tests ツールをCIパイプラインの一部として組み込むことで、AIが生成したコードがすべてのユニットテストをパスすることを確認できます。

{
  "pipeline": {
    "steps": [
      "generate_code_with_ai",
      "run_unity_tests",
      "check_compile_errors",
      "deploy_to_staging"
    ]
  }
}

mcp-unityのパフォーマンスと制約

WebSocket通信のレイテンシ

mcp-unityはローカルのWebSocket通信を使用しているため、ネットワーク遅延の影響はほとんどありません。ただし、Unityプロジェクトの規模が大きくなると、unity://scenes-hierarchy や unity://assets リソースの返却データが大きくなり、MCPの応答時間が増加することがあります。

プロジェクト規模別のパフォーマンス目安：

get_console_logs ツールにはページネーションサポートが実装されており、大規模プロジェクトでも効率的にログを取得できます。

対応しない操作

mcp-unityはUnity Editorの操作に特化しており、以下の操作は対応していません。

• Unity Playモードでのリアルタイムゲームロジックの変更（Editorのみ対応）
• GitのブランチやPull Requestの操作（これはIDEのGit連携に委ねる）
• UnityのAsset Store購入・ダウンロード
• ライセンス認証に関わる操作

同時接続の制限

デフォルトでは1つのMCPクライアントがWebSocketサーバーに接続します。複数のAI IDEから同時にUnity Editorを操作することは想定されていません。チームで使う場合は、どのメンバーがいつUnityを操作するかの調整が必要です。

mcp-unityを支えるMCPエコシステム

mcp-unityはMCPエコシステムの一部として機能します。他のMCPサーバーとの組み合わせで、さらに強力なワークフローを構築できます。

MCP標準化の意義

mcp-unityが独自APIではなくMCP標準プロトコルを採用したことの意義は大きいです。MCP対応IDEが増えれば、mcp-unity側の追加対応なしに自動的に新IDEをサポートできます。実際に2025〜2026年にかけてClaude Code・Codex CLI・GitHub Copilotなど主要AIツールが次々とMCPをサポートし、mcp-unityの対応IDEが自然に拡大しています。

MCPエコシステム全体についてはClaude Codeベストプラクティスでも解説しています。

まとめ

mcp-unityは、MCPプロトコルを通じてUnity EditorとAI IDEを統合する実用的なオープンソースプラグインです。30種類以上のMCPツールにより、GameObjectの操作からシーン管理、テスト実行、マテリアル設定まで幅広いUnity操作をAIから直接制御できます。

主な強みは以下の3点です。第一に、MCP標準プロトコルの採用により、Cursor・Claude Code・Codex・Windsurf・GitHub Copilot・Google Antigravityという主要AI IDEすべてに対応していること。第二に、C#プラグインとNode.jsサーバーの2層構造により、拡張性が高くカスタムツールを追加しやすいこと。第三に、batch_execute ツールによって複数操作を原子的に実行でき、大規模なシーン操作も効率的に行えること。

Unity 6.2の公式AI機能とは競合するものではなく、Editor操作の自動化と外部AI IDEの統合という観点で補完的な役割を果たします。MIT ライセンスのオープンソースプロジェクトとして、コミュニティによる継続的な機能追加も期待できます。

MCPを活用したより高度な開発を検討する場合は、Claude Codeベストプラクティスも参考にしてください。

参照ソース

• CoderGamester/mcp-unity - GitHub
• Model Context Protocol 公式ドキュメント
• Unity Package Manager ドキュメント
• Node.js 公式サイト