Unity MCPをClaude Codeで使う方法 — 公式サーバーの接続手順

Unity公式MCPサーバーとは

結論から書くと、Unity公式のMCPはパッケージcom.unity.ai.assistantに入っており、別途サーバーを用意する必要はありません。Claude Code側では、リレーバイナリを--mcp付きで登録するだけです。外部クライアントの接続はUnity側の承認が済むまでツールを呼べないため、承認なしに操作される心配はありません。Cursorも同じ形のJSONで登録できます。

Unity MCPは、Unity Editorに組み込まれたMCP(Model Context Protocol)ブリッジです。Claude CodeやCursorのようなMCP対応クライアントをUnity Editorに接続し、シーン作成・アセット管理・コード生成といった作業を標準化されたツール呼び出しで自動化します。パッケージcom.unity.ai.assistantに同梱されており、Unity 6以降のEditorで動きます。

Editorが起動するとMCPブリッジが自動的に立ち上がり、ローカルのIPCチャネル(Windowsは名前付きパイプ、macOS/LinuxはUnixソケット)を開きます。~/.unity/relay/には中継用のリレーバイナリが自動インストールされ、これがAIクライアントから起動されるMCPサーバープロセスの実体です。リレーはブリッジに接続し、Unityの機能をMCPツールとして公開します。

呼び出しは、次の4段を順にたどります。

MCPブリッジを持たないGodotの場合は、CLIとGDScriptだけで完結します。違いはClaude CodeでGodotゲーム開発を始める手順で扱っています。

前提条件

Claude Codeから接続するには次の2点が要ります。

• Unity 6(6000.0)以降で、com.unity.ai.assistantパッケージが導入されたプロジェクト
• MCP対応のAIクライアント(Claude Code、Cursor、Windsurf、Claude Desktopなど)

本記事が参照する公式マニュアルは、com.unity.ai.assistantパッケージ2.0.0-pre.1(プレリリース版)のドキュメントです。正式リリースまでに手順や設定項目が変わる可能性があります。Claude Code側でMCPサーバーを追加する一般的な仕組み(claude mcp addの構文やスコープ)はClaude Code MCP設定ガイドで扱っているので、初めてMCPサーバーを足す場合はあわせて確認してください。

Claude Codeへ接続する手順

ステップ1: Unity側のブリッジを確認する

Unity EditorでEdit > Project Settings > AI > Unity MCPを開きます。Bridge statusが緑の「Running」になっていれば起動済みです。「Stopped」と表示されている場合はStartを選択します。ブリッジ自体はEditor起動時に自動で立ち上がる設計で、手動操作が要るのは止まっているときだけです。

ステップ2: Claude Code側にMCPサーバーを登録する

Unity MCP設定ページの「Integrations」セクションには、対応クライアントを自動設定する「Configure」があります。一覧にClaude Codeがあればそこから設定できますが、この記事では実機のUnityで確かめていません。手動で設定するなら、Claude Code側はclaude mcp addで書けます。macOS(Apple Silicon)の例です。

claude mcp add -s project unity-mcp -- \
  ~/.unity/relay/relay_mac_arm64.app/Contents/MacOS/relay_mac_arm64 --mcp

--より後ろがそのままサーバー起動コマンドとして渡ります。--mcpをClaude Code自身のオプションと取り違えさせないための区切りです。パスにクォートを付けて~をシェルに展開させなかった場合、Claude Code v2.1.285で作業用の空ディレクトリに対して実行した結果は次のとおりです。

Added stdio MCP server unity-mcp with command: ~/.unity/relay/relay_mac_arm64.app/Contents/MacOS/relay_mac_arm64 --mcp to project config
File modified: <作業ディレクトリ>/.mcp.json

生成された.mcp.jsonは次の内容でした(パスは~のまま保存されています)。

{
  "mcpServers": {
    "unity-mcp": {
      "type": "stdio",
      "command": "~/.unity/relay/relay_mac_arm64.app/Contents/MacOS/relay_mac_arm64",
      "args": [
        "--mcp"
      ],
      "env": {}
    }
  }
}

Unityのマニュアルが載せる例はcommandとargsだけです。CLIで登録するとtypeとenvが補われ、-s projectならプロジェクト直下の.mcp.jsonに入ります。既定のスコープはlocalで、userとprojectも選べます。スコープの違いはClaude Code MCP設定ガイドにあります。

注意が要るのは~です。Claude Codeはcommandの~を展開しません。v2.1.285で、実在する~/.local/bin/claudeを'~/.local/bin/claude' mcp serveとして登録してclaude mcp getを実行すると、Failed to connectとなり、原因としてENOENT: no such file or directory, posix_spawn '~/.local/bin/claude'が表示されました。上のクォート付きの登録結果や、Unityのマニュアルが載せるJSON例をそのまま使うと、リレーが起動できません。クォートを外してシェルに展開させるか、.mcp.jsonを手書きするなら${HOME}を使います。commandでの環境変数展開は、Claude Codeの公式ドキュメントが明記している機能です。

{
  "mcpServers": {
    "unity-mcp": {
      "type": "stdio",
      "command": "${HOME}/.unity/relay/relay_mac_arm64.app/Contents/MacOS/relay_mac_arm64",
      "args": ["--mcp"]
    }
  }
}

シェルが展開した絶対パスは、プロジェクトスコープで.mcp.jsonを共有すると他のメンバーの環境で合いません。共有するなら${HOME}の形が向きます。

リレーバイナリのパスはOSとアーキテクチャで変わります。

argsの--mcpフラグは必須です。リレーバイナリはMCPサーバー以外の動作モードも持つため、このフラグでMCPサーバーとして動かすことを明示します。

設定前に、リレーバイナリが実際にインストールされているかを確認しておくと事故が減ります。

ls -la ~/.unity/relay/

ファイルが無い場合はUnity Editorを一度再起動してください。インストーラーはEditor起動時にパッケージ内のバイナリをコピーします。

ステップ3: 接続を承認する

Claude Codeのような外部MCPクライアントが初めて接続すると、Unity MCP設定ページの「Pending Connections」に保留中の接続として表示されます。Acceptを選ぶまでツールは呼び出せません。承認済みのクライアントは、次回以降は再承認なしで自動的に再接続します。

接続経路によって承認の要否が変わります。

ステップ4: 動作確認する

UnityとClaude Codeの両方を起動した状態で、Unity MCP設定ページの「Connected Clients」にクライアントが表示されていれば接続は成立しています。Claude Code側でもUnity_ManageSceneやUnity_ReadConsoleといったツール名が一覧できます。

簡単な動作確認として、Claude Codeで次のように指示します。

Read the Unity console messages and summarize any warnings or errors.

クライアントがUnity_ReadConsoleツールを使ってUnityのコンソール出力を取得し、要約を返せば設定は完了です。

Unity MCPが公開する主な機能

公式マニュアルが挙げる主要機能は次の5つです。

個別のツールの有効・無効は、Project Settingsの「Unity MCP」ページにあるツール一覧のトグルで切り替えられます。

カスタムツールを登録する

Unity MCPは属性ベースでカスタムツールを追加できます。もっとも単純な形は、staticメソッドに[McpTool]を付ける方法です。

using Unity.AI.MCP.Editor.ToolRegistry;
 
[McpTool("my_tool", "Description of what this tool does")]
public static object MyTool(MyParameters parameters)
{
    return new { success = true, message = $"Processed {parameters.Name}" };
}
 
public class MyParameters
{
    [McpDescription("Target name")]
    public string Name { get; set; } = "default";
}

Editor起動時にMcpToolRegistryがTypeCacheでアセンブリを走査し、[McpTool]が付いたメソッドを自動で発見・登録します。パラメータの型からJSONスキーマも自動生成されるため、スキーマを手書きする必要はありません。登録方式は公式マニュアルで4種類あります。型付きパラメータのstaticメソッド(上の例)、JObjectを受けるstaticメソッドに[McpSchema]でスキーマを付ける方式、状態を持たせたいツール向けのクラス実装(IUnityMcpTool<T>)、実行時に動的に登録・解除するMcpToolRegistry.RegisterToolのランタイムAPIです。属性ベースでツールスキーマを生成する設計は、.NET公式のMCP C# SDKが採用する[McpServerTool]パターンとも発想が近く、Unity固有の独自属性である点が異なります。

よくあるつまずき

ブリッジが起動しないケースの多くは、スクリプトのコンパイルエラーかパッケージの導入不備が原因です。明示的に停止された場合も起動しません。Unity Consoleでコンパイルエラーを解消し、Window > Package Managerでcom.unity.ai.assistantが入っていることを確かめたうえで、Edit > Project Settings > AI > Unity MCPでStartを選び直すと復旧します。

クライアントが接続できない場合は、--mcpフラグの付け忘れと、リレーバイナリのパス指定ミスが典型的な原因です。パスの~が展開されないままの登録も、同じく起動失敗になります。公式のトラブルシューティングは、Integrationsからクライアントを設定し直す方法を挙げています(一覧にClaude Codeがある場合)。

接続はできてもツールが呼び出せない場合は、Pending Connectionsで承認待ちのままになっていないかを確認します。ステップ3の承認操作を忘れると、接続自体は成立していてもツール呼び出しはすべて失敗します。

カスタムツールが一覧に出てこない場合は、[McpTool]を付けたメソッドがpublic staticになっているか、クラスベースの場合はIUnityMcpToolを実装しパラメータなしコンストラクタを持っているかを確認します。ツール自体がUnity MCP設定ページで無効化されていないかも見ておくとよいでしょう。カスタムツールを置いたアセンブリがTypeCacheの走査対象外になっている場合も、一覧に出ません。それでも接続そのものに問題がありそうなときは、クライアント側の設定・起動・認証・ツール表示を4層に分けて追うMCPサーバーに接続できないときの切り分け手順が一般的な原因の絞り込みに使えます。

リレーバイナリ自体が無いケースも起きます。インストーラー(ServerInstaller)はEditor起動時に走りますが、途中で中断されたりパッケージディレクトリにアクセスできなかったりすると失敗します。Editorを再起動してインストーラーを再実行させるのがまず試すべき対処です。それでも解決しない場合は、Unity MCP設定ページの「Locate Server」ボタンでパッケージに同梱されたバイナリを見つけ、手動でコピーする回避策があります。パッケージ側にPackages/com.unity.ai.assistant/RelayApp~/ディレクトリが存在するかも確認ポイントです。

応答が遅い・タイムアウトする場合は、Unityがアセットのインポートやビルド、コンパイルなど重い処理で塞がっていないかを確認します。進捗バーが表示されているならその処理の完了を待ち、解消しなければEditorを再起動してキャッシュ状態をクリアします。同時に接続するMCPクライアントの数を減らすことも有効です。

Unity MCP設定ページの「Show Debug Logs」を有効にすると、接続試行・ツール検出の詳細・コマンド実行のトレース・エラー情報がログに出るため、上記で解決しない場合の次の手がかりになります。カスタムツールが出ない場合も、ここで検出の詳細を追えます。

まとめ

Unity公式MCPサーバーは、com.unity.ai.assistantパッケージに同梱されたリレーバイナリとEditor内蔵のブリッジで動きます。Claude Code側でやることは、リレーバイナリのパスを--mcpフラグ付きで登録し、Unity側のPending Connectionsで初回接続を承認するだけです。組み込みツールでシーンやコンソールの操作はすぐ試せ、[McpTool]属性を使えば自作ツールも同じ仕組みで公開できます。接続できないときは、まずブリッジの起動状態・リレーバイナリの有無・--mcpフラグの3点を疑うと切り分けが早くなります。C#スクリプトの実装とコンパイル確認をコマンドラインだけで回したい場合は、Claude CodeでUnityゲーム開発を進めるも参考になります。