Unity-MCP（AI Game Developer）

基于 Model Context Protocol 的 AI 游戏开发助手，通过 100+ 内置工具将 Claude、Cursor、Copilot、Gemini 等 AI 代理无缝接入 Unity Editor 与 Runtime，实现代码编写、场景构建、资产管理及运行时 NPC 交互的全链路自动化。

项目定位#

Unity-MCP 解决了传统 AI 编码助手缺乏对 Unity 引擎内部状态（场景层级、资产、运行时实例）感知与操控能力的问题，使 AI 能直接参与游戏构建与调试，而非仅生成代码片段。

核心能力#

AI 代理兼容性#

无厂商锁定，原生支持 Anthropic Claude、OpenAI Codex、Microsoft Copilot、Google Gemini 等任意 MCP 兼容客户端，包括 Claude Code、Claude Desktop、Cursor、VS Code Copilot、Gemini CLI 等。

100+ 内置 MCP Tools#

Project & Assets：资产搜索/创建/删除/复制/移动、预制体管理、材质创建、UPM 包管理
Scene & Hierarchy：GameObject 创建/销毁/复制/修改、组件增删改查、场景管理、多视角截图（Game View / Scene View / Camera）
Scripting & Editor：C# 脚本读写/创建/删除、Unity 日志获取、编辑器状态控制（播放/暂停）、测试运行、C# 反射方法查找与调用

高级执行机制#

Skills 系统：基于操作系统、Unity 版本、项目已安装插件自动生成 AI 技能描述，增强上下文理解
Reflection 驱动：通过 C# Reflection 动态发现和调用项目代码库中任意方法，包括私有方法和编译后 DLL 中的方法
即时编译：使用 Roslyn 进行 C# 代码片段的即时编译与执行

Runtime 支持#

可在已编译的游戏内部运行 LLM 交互，实现动态 NPC 行为驱动与实时 AI 调试（如国际象棋 AI Bot）。

架构设计#

项目采用三层解耦架构：

Unity-MCP-Plugin（C#）：运行在 Unity Editor 或游戏 Runtime 中，通过反射和 Roslyn 将 Unity API 及项目代码暴露为 MCP 工具/资源/提示
Unity-MCP-Server（Node.js/TypeScript）：中间代理服务，桥接 AI 代理和 Unity Plugin，支持 streamableHttp 和 stdio 两种传输协议
AI Agent / MCP Client：各类 AI 客户端通过标准 MCP 协议与 Server 交互

关键实现包括 MainThread 调度（通过 MainThread.Instance.Run() 安全跨越线程边界调用 Unity API）以及声明式属性系统（[McpPluginTool]、[McpPluginResource]、[McpPluginPrompt]）。

安装部署#

Unity Package 安装#

openupm add com.ivanmurzak.unity.mcp

或从 GitHub Releases 下载 .unitypackage 导入。

CLI 安装（推荐）#

npm install -g unity-mcp-cli
unity-mcp-cli install-plugin ./MyUnityProject
unity-mcp-cli login ./MyUnityProject
unity-mcp-cli open ./MyUnityProject

Docker 部署#

拉取镜像 ivanmurzakdev/unity-mcp-server 进行容器化部署。

初始化配置：在 Unity Editor 中打开 Window/AI Game Developer，点击 Auto-generate Skills 或 Configure MCP 完成对接。

自定义扩展#

通过 C# 属性声明自定义 MCP Tool：

[McpPluginToolType]
public class Tool_GameObject
{
    [McpPluginTool("MyCustomTask", Title = "Create a new GameObject")]
    [Description("Explain here to LLM what is this, when it should be called.")]
    public string CustomTask(
        [Description("Explain to LLM what is this.")] string inputData)
    {
        return MainThread.Instance.Run(() => {
            return $"[Success] Operation completed.";
        });
    }
}

Runtime 接入示例：

var mcpPlugin = UnityMcpPluginRuntime.Initialize(builder =>
{
    builder.WithConfig(config =>
    {
        config.Host = "http://localhost:8080";
        config.Token = "your-token";
    });
    builder.WithToolsFromAssembly(Assembly.GetExecutingAssembly());
}).Build();
await mcpPlugin.Connect();

Server 配置#

环境变量	命令行参数	说明
`MCP_PLUGIN_PORT`	`--port`	连接端口（默认 8080）
`MCP_PLUGIN_CLIENT_TIMEOUT`	`--plugin-timeout`	插件连接超时（ms，默认 10000）

扩展生态#

提供附加工具集：AI Animation、AI ParticleSystem、AI ProBuilder。

待确认信息#

Unity 最低版本要求未在 README 中明确标注
云服务（CLI login）的免费/付费政策未说明
MCP Server 具体使用的 Node.js 框架未在 README 中说明