KitWright Unity MCP

Unity 版 KitWright MCP

适用于 Unity Editor 的高级 MCP 服务

中文 | 英文

💖 如果你觉得这个项目有用，请考虑点个 Star。这能帮助更多 Unity 开发者发现它，并支持持续开发。

Unity 版 KitWright MCP 是一个采用 MIT 许可证的 Unity Editor MCP 服务，可让 Claude Code、Cursor、LM Studio、Windsurf、Codex 和 VS Code Copilot 等 AI 助手直接在运行中的 Unity 项目里操作。

用一句话描述你的游戏——AI 助手便会通过 Unity 版 KitWright MCP 的 274 个内置工具，在 Unity 中构建游戏，涵盖场景创建、脚本生成、运行时验证、输入模拟、性能分析和编辑器自动化。

“构建一款 10x10 网格的贪吃蛇游戏，包含食物生成、得分 UI 和游戏结束界面”

AI 助手会通过 Unity 版 KitWright MCP 完成这些工作：创建场景、生成所有脚本、设置 UI 并配置游戏逻辑——只需一条提示词。

演示——AI 通过 MCP 工具搜索项目预制件并构建城市场景。观看高清 MP4。

快速开始

如果你只想快速连接，请完成以下三步：

• 从 Git URL 安装 Unity 包
• 打开 Window > KitWright > MCP Window，并从 Server 选项卡启动服务
• 使用内置的一键客户端配置

1. 通过 UPM 安装（Git URL）

在 Unity 中，前往 Window → Package Manager → + → Add package from git URL：

https://github.com/kitwright/unity-mcp.git#upm

💡 在克隆或安装之前，如果能在 GitHub 上点个 ⭐，我们将不胜感激。

可选：通过 OpenUPM 安装

如果你希望 Unity Package Manager 显示基于注册表的包版本历史记录并允许选择版本，请从 OpenUPM 安装，而不是从 Git 安装。

使用 OpenUPM CLI：

openupm add com.kitwright.unity.mcp

或者在 Packages/manifest.json 中手动添加作用域注册表：

{
  "scopedRegistries": [
    {
      "name": "OpenUPM",
      "url": "https://package.openupm.com",
      "scopes": [
        "com.kitwright"
      ]
    }
  ],
  "dependencies": {
    "com.kitwright.unity.mcp": "1.0.1"
  }
}

如果之前通过 Git URL 安装，请先移除 Git 依赖项，再从 OpenUPM 安装。通过 Git 安装的包在 Unity 中只会显示解析后的 Git 版本，不会显示基于注册表的版本历史记录列表。

可选：从 Unity Asset Store 安装

导入 Asset Store 包时会显示 This Unity Package has Package Manager dependencies 对话框。选择 Install/Upgrade——此包需要 com.unity.nuget.newtonsoft-json，如果跳过提示，项目将缺少此依赖项，导致所有 KitWright 脚本都无法编译。

如果已经选择了 Skip，该包会在下一次域重新加载时提示为你安装依赖项；你也可以通过 Window → Package Manager → + → Add package by name 自行添加：

com.unity.nuget.newtonsoft-json

2. 启动 MCP 服务

菜单：Window → KitWright → MCP Window，然后在 Server 选项卡中启动服务。

服务默认在 http://127.0.0.1:8765/ 上启动。

Broker Mode 是默认传输方式。它使用 Unity 附带的 Mono 运行一个轻量级本地代理，为 MCP 客户端保持相同的 127.0.0.1 端口，无需更改客户端配置，并能在 Unity 脚本重新编译和 Play Mode 域重载期间保持连接。如果代理无法启动，服务会自动回退到进程内直接 HTTP；你也可以在 Server 选项卡中关闭代理模式，始终使用直接 HTTP。

此窗口有五个选项卡：Server、Settings、Skills、Tool Exposure 和 Integrations。

如果要编辑 core 或 full 实际公开的工具，请打开 Tool Exposure 选项卡。

如果需要调整 execute_code 安全默认值或插件调试日志记录，请打开 Settings 选项卡。

3. 配置 AI 客户端

请先使用 Server 选项卡中的内置 One-Click MCP Configuration。

选择目标客户端并点击 Configure，软件包便会为你写入推荐的 MCP 配置项。

对于 Claude Code、Cursor 和 Codex，点击 Configure + Skills 还可以安装默认的项目 MCP 工作流技能。

如果要为当前 Unity 项目添加特定的 AI 指引，请打开 Skills 选项卡，选择支持的平台并安装默认的 unity-mcp-workflow 技能。

如果你偏好手动编辑配置文件，可将以下示例用作备用参考：

{
  "mcpServers": {
    "kitwright": {
      "type": "http",
      "url": "http://127.0.0.1:8765/"
    }
  }
}

{
  "mcpServers": {
    "kitwright": {
      "url": "http://127.0.0.1:8765/"
    }
  }
}

{
  "mcpServers": {
    "kitwright": {
      "url": "http://127.0.0.1:8765/"
    }
  }
}

{
  "servers": {
    "kitwright": {
      "type": "http",
      "url": "http://127.0.0.1:8765/"
    }
  }
}

{
  "mcpServers": {
    "kitwright": {
      "url": "http://127.0.0.1:8765/"
    }
  }
}

{
  "mcpServers": {
    "kitwright": {
      "type": "http",
      "url": "http://127.0.0.1:8765/"
    }
  }
}

[mcp_servers.kitwright]
url = "http://127.0.0.1:8765/"

4. 验证连接

打开 AI 客户端，先尝试几个安全请求：

• “调用 get_scene_info 并告诉我当前打开的是哪个场景。”
• “读取 unity://project/context 并总结当前编辑器状态。”
• “使用 execute_code 返回当前活动场景的名称。”

如果这些操作都能正常运行，则 MCP 服务、资源和主要执行工具均已正确连接。

5. 开始构建

打开 AI 客户端并尝试：“创建一个包含 5 个浮空平台的 3D 平台跳跃关卡”

开始之前

• 此软件包仅适用于 编辑器。它不会向构建后的游戏添加运行时组件。
• MCP 服务默认在 http://127.0.0.1:8765/ 启动。
• 本地 MCP 服务设置保存在 UserSettings/KitWrightMcpSettings.json 中。
• 软件包默认使用 core MCP 工具配置，以减少 AI 客户端的工具列表冗杂度。core 目前提供 43 个高价值工具，主要涵盖 execute_code、播放模式控制、输入模拟、截图、性能检查、日志、编译检查、结构化对象定位与组件编辑、编辑器选中项／预制件阶段状态、实时 C# API 反射、Unity 文档查询，以及作为低门槛备用方案的 execute_menu_item。如果想使用全部 274 个工具，请在 Server 选项卡中切换到 full。
• execute_code 安全检查和更严格的文件系统防护默认已在 Settings 选项卡中启用。该防护会拦截明显具有破坏性的代码片段、范围广泛的 System.IO 写入、原始文件流，以及绝对路径、用户路径、系统路径和路径遍历。它能防止意外，而非恶意行为：safety_checks 是工具参数，因此任何能调用 execute_code 的客户端都可以传入 safety_checks=false，跳过源码阻止列表和编译程序集防护。它既不是沙箱，也不是安全边界——请参阅 SECURITY.md。
• 插件调试日志默认关闭，也可在 Settings 选项卡中启用。警告和错误始终会写入 Unity Console。
• 所有公开的 MCP 工具都会直接运行，不提供额外的审批开关。
• 窗口会在后台检查更新；有新版时，会在标题栏中显示 Update 按钮——它可以原地更新 Git 安装，或自动下载并导入最新的 unitypackage。

为什么选择此项目

• execute_code 优先 — 围绕一个内存中的 C# 执行工具进行优化，以实现丰富的编辑器／运行时编排。详情请参阅下文的 execute_code：内存中的 C# 执行。
• 默认安全检查 — execute_code 现在提供持久的默认启用安全开关，包括更严格的文件系统防护，适用于无法清晰展示单次调用参数的客户端
• 播放模式自动化 — 在同一 MCP 会话中进入播放模式、模拟键盘／鼠标输入、截取屏幕截图、检查日志并验证行为
• 内置项目上下文 — 提供项目状态、活动场景、选中项、编译状态、控制台输出和 MCP 交互历史的实时资源
• 默认精简，需要时启用完整配置 — core 提供精简的高价值工具集；full 提供 274 个工具
• 单一 Unity 软件包 — 无需额外审批界面，无需点击操作外部守护进程，Unity 端插件本身也不要求安装 Python
• 可扩展 — 可通过基于特性的发现机制添加自定义工具，也可按需将 Unity 连接到外部 MCP 服务

亮点

• 274 个内置工具 — 场景编辑、资源、脚本、运行模式控制、截图与截图差异比较、性能分析、提示词、资源、结构化对象定位、基于 SerializedObject 的组件和项目设置编辑、动画器创作、复合 uGUI 控件、编辑器状态检查、菜单项回退，以及跨 57 个模块的编辑器自动化。完整列表：TOOLS.md
• 结构化返回值 + instanceId 链式调用 — 工具以 JSON 格式返回 {success, message, data}，并提供稳定的 instanceId 字段，让 Agent 能可靠地链式调用 by_id，而无需重新按名称解析对象
• 用于 execute_code 的 IKitWrightCommand — 全新的代码片段模板，支持自动撤销（ctx.RegisterObjectCreation / ctx.RegisterObjectModification / ctx.DestroyObject）、结构化日志（ctx.Log/LogWarning/LogError），并向 Agent 返回已记录的变更日志
• 资源与提示词 — 实时项目上下文、场景/选中项/错误资源、资源模板，以及可复用的工作流提示词
• 输入模拟 + 截图 — 通过键盘/鼠标模拟控制运行模式，并用游戏/场景截图验证结果
• 内置更新 — MCP 窗口会显示新版本，并重新拉取 Git 包或自动导入最新的 unitypackage
• 集成选项卡 — 检测 Hot Reload、Memory Profiler、Addressables、Input System、Timeline、URP 和 Test Framework，并显示各项集成可启用的工具
• 一键配置客户端 — 直接在 Unity 窗口中为 19 个目标写入 MCP 配置项：Claude Code、Cursor、VS Code（含 Insiders）、Codex、Windsurf、Cline、Kiro、Trae、Rider（含 Junie）、Kimi Code、Qwen Code、Antigravity、Kilo Code、OpenCode、GitHub Copilot CLI、CodeBuddy CLI 和 Roo Code
• 工具暴露控制 — 编辑 core 和 full 实际暴露的工具
• 项目技能管理器 — 为受支持的 AI 客户端配置项目级技能，目前会安装默认的 unity-mcp-workflow 技能
• MCP 设置 — 调整 execute_code 安全默认值，并在排查 MCP 连接或工具执行问题时启用插件详细调试日志
• 不依赖特定厂商 — 适用于任何支持 MCP 的 AI 客户端：Claude Code、Cursor、LM Studio、Windsurf、Codex、VS Code Copilot 等

execute_code：内存中的 C# 执行

execute_code 是 KitWright MCP for Unity 的核心。它让 AI 编写一段 C# 代码片段，通过以 Roslyn 为优先的内存执行流程进行编译，并在编辑器线程上运行——Agent 无需将任何项目文件写入磁盘，即可使用完整的 Unity Editor 和运行时 API。

• 编译不占用项目空间——代码片段首先使用 Unity 自带的 Roslyn csc 编译，同时保留内存编译和执行流程。不会在 Assets/ 下写入 .cs 文件，不会触发域重载，也不会触碰代码片段本身未操作的项目状态。
• 运行前确保编辑器就绪——每次调用都会刷新 AssetDatabase，并等待待处理的编译完成，然后再编译代码片段，因此会自动拾取外部文件的更改，无需单独调用 request_recompile。
• 自动撤销 + 结构化日志（推荐模板）——实现 IKitWrightCommand 并使用注入的 ExecutionContext，即可让每个创建、修改或销毁的对象都支持编辑器撤销，并将更改日志返回给 Agent。

using UnityEngine;
using UnityEditor;
using KitWright.Editor.Tools.Helpers;
using KitWright.Editor.Tools.Scripting;

public class CommandScript : IKitWrightCommand
{
    public void Execute(ExecutionContext ctx)
    {
        var go = GameObject.CreatePrimitive(PrimitiveType.Cube);
        ctx.RegisterObjectCreation(go);          // auto-Undo + tracked
        ctx.Log("Created {0}", go.name);
        ctx.ReturnValue = GameObjectSerializer.Describe(go, includeComponents: false);
    }
}

响应包含 { logs, created, modified, destroyed, returnValue }，因此 Agent 无需重新查询场景，就能准确核验发生的更改。

旧版模板（public static string Run()）仍受支持，适用于一些临时检查代码片段，无需进行结构化追踪。

何时使用 execute_code，何时使用专用工具——execute_code 适用于多步骤编排、新颖的读取需求，以及将 5–10 次范围狭窄的工具调用串联起来反而不如一段代码片段简洁的情况。对于单字段组件编辑、简单的选择更改或已有工具覆盖的操作，优先使用专用工具——调用成本更低，也更容易核验。

与 Coplay 的对比

下表将本仓库与 Coplay 在 GitHub 上公开记录的开源 unity-mcp 仓库行为进行比较（依据 v10.0.0 和公开文档站点核对）。

Coplay 列的信息来源：CoplayDev/unity-mcp 及其工具参考

与 Unity AI Assistant 的比较

下表将本仓库与 Unity Technologies 官方的 com.unity.ai.assistant 包（截至 2026-05 的 v2.7.0-pre.2）进行了比较。

如需了解两种方案的详细比较，请参阅 KitWright MCP for Unity 与 Unity AI Assistant 的详细比较（中文）。

MCP 能力

当前的开源包提供四个高价值能力层：

• 工具 — full 配置共 274 个工具，core 配置包含 43 个重点工具
• 主要执行方式 — 使用 execute_code 进行丰富的编辑器/运行时编排
• 提示词 — 工作流提示词，例如 fix_compile_errors、runtime_validation 和 create_playable_prototype
• 资源 — 项目上下文、场景摘要、选中状态、编译错误、控制台错误、MCP 交互历史，以及针对场景对象、组件和资源路径的资源模板

内置工具

KitWright MCP for Unity 提供 57 个模块中的 273 个工具函数（core 配置开放其中 53 个）。

📖 查看每个工具及其说明：TOOLS.md。

📊 如需查看完整的 Profiler 工具参考、实现说明、已知限制和测试报告，请参阅 PROFILER_TOOLS.md。

添加自定义工具

项目可以使用与内置工具相同的属性声明自己的 MCP 工具。将类放在 Editor 程序集中——KitWright.Editor 是 autoReferenced，因此无需设置 asmdef 引用：

using System.ComponentModel;
using KitWright.Editor.Tools;

[ToolProvider("MyTools")]
public static class MyCustomTools
{
    [Description("Spawns enemies at random positions in the scene")]
    public static string SpawnEnemies(
        [ToolParam("Number of enemies to spawn", Required = true)] int count,
        [ToolParam("Prefab path in Assets")] string prefabPath)
    {
        // Your implementation here
        return $"Spawned {count} enemies";
    }
}

系统会自动发现类中的公共静态方法，将其转换为 snake_case（spawn_enemies），并根据参数列表生成 JSON Schema 定义，通过 MCP 暴露。对于不会修改场景或项目的方法，请标记 [ReadOnlyTool]，这样客户端会收到其 annotations.readOnlyHint。

项目声明的工具会在所有配置中暴露，包括默认的 core，因为编写自定义工具本身就代表明确选择使用；否则，自定义工具对大多数客户端连接的配置将不可见。它们仍会显示在工具暴露选项卡中，因此可在那里配置配置，将其像内置工具一样关闭。

架构

MCP Server (HTTP JSON-RPC 2.0)
    └─ MCPRequestHandler (protocol handling)
        └─ MCPExecutionBridge
            └─ FunctionInvoker (reflection-based invocation)
                └─ Tool Functions (274 built-in tools across 57 modules)

External AI Client → HTTP Request → MCPRequestHandler → MCPExecutionBridge → FunctionInvoker → tool method

要求

• Unity 2022.3 或更高版本
• com.unity.nuget.newtonsoft-json — 通过 UPM 和 OpenUPM 安装时会自动引入；通过 Asset Store 导入时，可在 Package Manager 依赖项对话框中选择安装
• com.unity.ugui 和 com.unity.test-framework — 已声明为依赖项，默认 Unity 项目中已包含

贡献

欢迎贡献！提交 PR 前，请阅读贡献指南。

安全

发现漏洞？请私下报告——参见安全策略。

许可证

MIT — 可免费用于使用、修改、分发，以及集成到商业或开源项目中。

KitWright 名称和徽标是 KitWright 项目的商标，不受 MIT 许可证涵盖。未经事先书面许可，不得使用该名称或徽标为衍生作品打造品牌，或暗示获得认可。品牌资产（Editor/Icons/ 下的文件）的所有权利均予保留。