Unity MCP

Unity MCP 集成框架

English Version | Tiếng Việt

这是一个向 AI Agent 开放 Unity Editor 的框架。无论由人手动执行，还是通过脚本调用，都会经过相同的路径。

• MCP 客户端直接连接 Editor 自身公开的 Streamable HTTP 端点 http://127.0.0.1:<port>/mcp。没有独立进程的 MCP 服务。已确认可与 Claude Code、Cursor、Codex、Gemini CLI、VS Code、Claude Desktop 配合使用。
• 也可以通过命令行 isuzu-unity-cli 调用相同的工具。提供的可执行文件是原生程序，不需要 Node 或 .NET 运行时。
• 只需为 C# static 方法添加 [McpTool]，即可定义工具。

初次使用时，请从配有图示的入门指南 Unity MCP 入门指南 开始。

必要条件

• Unity Editor 2022.3 或更高版本。EditMode 测试套件使用 Unity 6000.0.35f1 运行
• 请将 Git 客户端 2.14.0 或更高版本添加到 PATH。Unity 的 Package Manager 会用它获取 git URL 软件包（Unity 手册）。从下方的 VPM 仓库安装时不需要
• com.unity.nuget.newtonsoft-json 3.2.1。会作为依赖项自动解析

安装

在 Unity 的 Package Manager 中选择 Add package from git URL，然后输入以下 URL。

https://github.com/isuzu-shiranui/UnityMCP.git?path=jp.shiranui-isuzu.unity-mcp

在 VCC（VRChat Creator Companion）和 ALCOM 中，请添加 VPM 仓库 https://unity-mcp.shiranui-isuzu.dev/vpm.json。两者都会以 zip 格式下载软件包，因此通过此方式安装不需要 Git。入门指南的适用于 VCC・ALCOM 的情况中提供了一键添加链接和添加位置的界面截图。

安装 CLI。

# Windows
irm https://raw.githubusercontent.com/isuzu-shiranui/UnityMCP/main/install.ps1 | iex

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/isuzu-shiranui/UnityMCP/main/install.sh | sh

也可以直接从 GitHub Releases 下载可执行文件，并使用 SHA256SUMS 验证。如果安装了 .NET 10 SDK，也可以运行 dotnet tool install -g IsuzuUnityCli 安装。

接下来，注册 Agent 技能和 MCP 客户端。

isuzu-unity-cli setup                              # Claude Code / Codex 向けのスキル
isuzu-unity-cli setup --mcp --agent claude-code    # MCP クライアントへの登録

--agent 可选 claude-code / claude-desktop / codex / cursor / gemini / vscode。Claude Code 会将服务注册在 Unity 项目路径下，因此请在 Unity 项目文件夹中启动 Claude Code。也可以通过 Editor 的 Preferences > Unity MCP 页面进行注册。

各客户端的设置、面向 Claude Desktop 的扩展包和 stdio 桥接程序，请参阅 连接 MCP 客户端。

第一个命令

Editor 打开项目后，服务便会启动并公开 descriptor 文件。CLI 会读取该文件，因此无需指定端口或令牌。

isuzu-unity-cli projects                  # 起動中の Editor 一覧
isuzu-unity-cli tools                     # 利用可能なツール
isuzu-unity-cli call play_mode_status     # ツールの実行
isuzu-unity-cli verify                    # 再コンパイル → エラー抽出 → コンソールのエラー

verify 会将编辑脚本后的重新编译和错误收集合并为一次调用。添加 --test 还会运行测试。

如果同时启动了多个 Editor，请使用 --project <name> 进行选择。如果在项目目录中运行，则会自动选择。所有命令请参阅 CLI 参考。

工具

包括诊断（控制台、Editor.log、编译状态、测试、场景层级、读取资源）、创作（创建和修改 GameObject、组件、资源、场景、Prefab、Animator Controller）、渲染、Timeline / Recorder、构建、运行 C# 代码片段，以及合成对 Editor 的输入。创作工具每次调用都会合并为一次 Undo 操作。

只有在存在 com.unity.timeline 时才会提供 Timeline 工具；只有在同时存在 com.unity.recorder 和 com.unity.timeline 时才会提供 Recorder 工具；只有在存在 com.unity.test-framework 时才会提供 test_run 和 test_results。

工具列表和注意事项请参阅工具列表。在 MCP URL 中添加类似 ?group=diagnostics,authoring 的分组参数后，tools/list 只会返回该分组中的工具。

添加工具

只需在 Editor 端编写一个方法。

using System.Linq;
using UnityMCP.Editor.Core;
using UnityMCP.Editor.Core.Attributes;

internal static class MyTools
{
    [McpTool(
        "asset_find_by_type",
        "Find project assets of a given type. Prefer a narrow type and a small limit.",
        Idempotency = McpIdempotency.Safe)]
    public static string[] FindByType(
        [McpArg("type", "Unity type name, e.g. Material.")] string type,
        [McpArg("limit", "Maximum paths to return.")] int limit = 50)
    {
        return UnityEditor.AssetDatabase.FindAssets($"t:{type}")
            .Take(limit)
            .Select(UnityEditor.AssetDatabase.GUIDToAssetPath)
            .ToArray();
    }
}

这样就能同时通过 MCP 客户端和 CLI 调用。JSON Schema 会根据签名生成。[McpTool] 可指定的属性请参阅架构。

也可以不编写 C#，而通过 JSON 文件添加工具。请参阅定义工具。

文档

• 工具列表：工具表格和注意事项
• 连接 MCP 客户端：各客户端的设置、Claude Desktop 桥接程序、协议特性
• CLI 参考：所有命令、项目选择、退出代码、机器上需要放置的文件
• 定义工具：通过 JSON 文件添加 probe / script / sequence 工具
• 合成、记录和回放 Editor 输入：input_pointer / input_key / input_record / input_replay
• 架构：路径图、Editor 端类、设置、测试
• 故障排除
• 安全
• 更新步骤：各版本的升级方法，以及中间版本中的变更
• 从 v3 迁移
• CHANGELOG

セキュリティ

サーバーは 127.0.0.1 にだけバインドします。OPTIONS を除く全リクエストに bearer token が必要です。descriptor ファイルとトークンファイルは資格情報として扱ってください。これらを読めるものは、Editor 内でコードを実行できます。プレイヤービルドには、Development Build を含めて一切含まれません。詳細は セキュリティ にあります。

ライセンス

MIT