使用说明

Unity代码MCP服务器

搜索实时Unity项目

从MCP客户端检查活动场景、组件、资源、控制台输出、设置、播放模式状态和运行时值。

直接在编辑器内执行

通过在编辑器中执行C#，创建和修改游戏对象、预制件、ScriptableObjects、导入设置和其他Unity资源。

使用运行时反馈进行验证

运行编辑模式和游戏模式测试，进入游戏模式，模拟玩家输入，截图，阅读Unity控制台日志，并在操作后检查实时游戏状态。

示例代理工作流程：使用以下命令在闭环中玩乒乓球 enter_play_mode, execute_csharp_script_in_unity_editor, play_unity_game，以及 read_unity_console_logs 搜索运行时状态，执行输入操作，验证结果，并调整下一步行动。

真实工作流示例

看全城市工作流程示例及文字记录.

工具

execute_csharp_script_in_unity_editor

通过在Unity编辑器上下文中执行生成的C#脚本来执行任何任务。完全访问UnityEngine、UnityEditor API和反射。自动捕获日志、错误和返回值。

read_unity_console_logs

使用可配置的条目限制（1-1000，默认200）读取Unity编辑器控制台日志

运行单位测试

通过TestRunnerApi运行Unity测试。支持编辑模式、播放模式或两者。可以运行所有测试或按完全限定的测试名称进行筛选。

enter_play模式

进入Unity播放模式，暂停时间，并在触发转换后立即返回。旨在在游戏自动化工具之前使用。

play_unity_game

暂时取消暂停时间，模拟配置的输入系统操作，收集日志，并在完成后再次暂停。

get_unity_game_view_window_screenshot

将当前的Unity游戏视图捕获为图像，而无需通过游戏输入调用进行屏幕截图捕获。

exit_play_mode

退出Unity播放模式，取消播放时间，并在触发转换后立即返回。

获取单位信息

返回有关当前Unity编辑器项目和UnityCodeMcpServer设置的信息。

安全注意事项

此包以与Unity编辑器进程相同的权限执行LLM生成的C#代码（包括反射代码）。

建议：

在执行脚本之前，请先对其进行审查。
使用单独的Unity项目和/或在隔离环境（VM/容器）中运行Unity。

您有责任保护您的环境，并对执行的脚本造成的任何更改或数据丢失负责。

建筑

架构图：Unity代码MCP服务器包在Unity编辑器内运行，并通过文件支持的STDIO桥与外部MCP客户端（如LLM代理）通信。

STDIO传输

graph LR
    A["MCP Client<br/>AI Agent"] -->|STDIO| B["STDIO Bridge<br/>Python script"]
    B <-->|request/response files| C["Unity Code MCP Server<br/>Unity Editor"]

    style A fill:#e1f5ff
    style B fill:#fff3e0
    style C fill:#f3e5f5

快速开始

需求

Unity 2022.3 LTS或更高版本（在2022.3.62f3和6000.2.7f2上测试）
UniTask（异步/等待集成）：https://github.com/Cysharp/UniTask
uv （Python包管理器）用于捆绑的STDIO桥：https://docs.astral.sh/uv/.

安装

安装 uv:
- 请遵循以下说明https://docs.astral.sh/uv/getting-started/installation
在Unity项目中安装UniTask。打开 窗口>包管理器，单击 + 按钮，选择 从git URL添加包。。。，然后输入：

https://github.com/Cysharp/UniTask.git?path=src/UniTask/Assets/Plugins/UniTask

从Unity包管理器安装Unity代码MCP服务器。打开 窗口>包管理器，单击 + 按钮，选择 从git URL添加包。。。，然后输入：

https://github.com/Signal-Loop/UnityCodeMCPServer.git?path=Assets/Plugins/UnityCodeMcpServer

配置技能安装位置。打开 工具/UnityCodeMcpServer/显示或创建设置，滚动到技能部分，然后确认或更改安装目录。默认情况下，首次安装目标 .agents/skills/。安装或更新软件包时，技能会自动安装和更新。

首次运行

MCP客户端配置

打开你的Unity项目。Unity自动启动文件备份传输并监视 .unityCodeMcpServer/messages 在项目根中。
配置您的MCP客户端以运行捆绑的STDIO网桥。

工作室

示例配置（使用 uv 运行桥梁）：

这 unity-code-mcp-stdio 网桥通过以下方式将STDIO流量转发到Unity .unityCodeMcpServer/messages.

{
  "servers": {
    "unity-code-mcp-stdio": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "C:/path/to/UnityProject/Assets/Plugins/UnityCodeMcpServer/Editor/STDIO~",
        "unity-code-mcp-stdio"
      ]
    }
  }
}

服务器配置（Unity）

通过访问设置 工具/UnityCodeMcpServer/显示或创建设置.
配置 详细日志 用于详细诊断和可选设置 输入操作资产 为了 play_unity_game.

文件支持的传输通过以下方式交换请求和响应文件 .unityCodeMcpServer/messages 在Unity项目根目录中。

菜单命令

通用

工具/UnityCodeMcpServer/显示或创建设置 --在检查器中打开服务器设置资源

代理技能

Unity Code MCP服务器附带了一组 AI代理技能档案 （Markdown文档，教你的代理如何有效地使用服务器的工具）。每当安装或更新包时，这些技能都会自动安装到配置的目标目录中。

安装技能

打开服务器设置： 工具/UnityCodeMcpServer/显示或创建设置.
滚动到技能部分。
从下拉列表中选择安装目录：

GitHub 目标 .github/skills/
Claude 目标 .claude/skills/
Agents 目标 .agents/skills/
Custom 显示文件夹选择器，以便您可以选择任何目录

检查器显示当前选定的目标目录标签，以便您可以准确验证技能将被复制到哪里。
软件包安装和更新运行会自动复制技能。

只有新的或更改的 .md 文件被复制。跳过已更新（匹配内容哈希）的文件。

包括技能

技能	描述
`executing-csharp-scripts-in-unity-editor`	教代理何时以及如何使用 `execute_csharp_script_in_unity_editor`, `read_unity_console_logs`，以及 `run_unity_tests` 作为一条可靠的管道。涵盖了禁止的模式、调试循环和常见的脚本模式。
`unity-game-player`	教代理如何使用以下命令在闭环中玩和测试Unity游戏 `enter_play_mode`, `play_unity_game`, `execute_csharp_script_in_unity_editor`, `read_unity_console_logs`，以及 `exit_play_mode`。涵盖场景发现、基于数学的动作计时和自适应重感知。

扩展（添加工具）

通过在代码库中的任何位置实现相关接口（ITool、IToolAsync、IPrompt、IResource）来添加工具、提示、资源或异步工具。服务器将自动检测并注册它们。

同步工具

using System.Collections.Generic;
using System.Text.Json;
using UnityCodeMcpServer.Interfaces;
using UnityCodeMcpServer.Protocol;

public class EchoTool : ITool
{
    public string Name => "echo";

    public string Description => "Echoes the input text back to the caller";

    public JsonElement InputSchema => JsonHelper.ParseElement(@"{
            ""type"": ""object"",
            ""properties"": {
                ""text"": {
                    ""type"": ""string"",
                    ""description"": ""The text to echo""
                }
            },
            ""required"": [""text""]
        }");

    public ToolsCallResult Execute(JsonElement arguments)
    {
        var text = arguments.GetStringOrDefault("text", "");

        return ToolsCallResult.TextResult($"Echo: {text}");
    }
}

异步工具

using System.Collections.Generic;
using System.Text.Json;
using UnityCodeMcpServer.Interfaces;
using UnityCodeMcpServer.Protocol;
using Cysharp.Threading.Tasks;

public class DelayedEchoTool : IToolAsync
{
    public string Name => "delayed_echo";

    public string Description => "Echoes the input text after a specified delay (demonstrates async tool)";

    public JsonElement InputSchema => JsonHelper.ParseElement(@"{
            ""type"": ""object"",
            ""properties"": {
                ""text"": {
                    ""type"": ""string"",
                    ""description"": ""The text to echo""
                },
                ""delayMs"": {
                    ""type"": ""integer"",
                    ""description"": ""Delay in milliseconds before echoing"",
                    ""default"": 1000
                }
            },
            ""required"": [""text""]
        }");

    public async UniTask<ToolsCallResult> ExecuteAsync(JsonElement arguments)
    {
        var text = arguments.GetStringOrDefault("text", "");
        var delayMs = arguments.GetIntOrDefault("delayMs", 1000);

        await UniTask.Delay(delayMs);

        return ToolsCallResult.TextResult($"Delayed Echo (after {delayMs}ms): {text}");
    }
}

脚本执行上下文

默认情况下，脚本执行上下文包括以下程序集：

装配CSharp
汇编CSharp编辑器
系统。核心
UnityEngine。核心模块
UnityEditor。核心模块

Unity Code MCP服务器设置（资源/插件/UnityCodeMcpServer/Editor/Resources/UnityCode McpServerSettings.reset）允许配置其他程序集以包含在脚本执行上下文中。如果您的项目有生成的脚本需要引用的程序集，这将非常有用。

要添加其他程序集，请使用设置“其他程序集”部分。

STDIO电桥

请参阅以下桥梁文档 README_STDIO.md.

测试

Unity测试正在进行中 Assets/Tests/ 并且可以通过Unity测试运行器运行。

已知问题

GUID与项目中的现有dll文件冲突

Unity Code MCP服务器在其包中包含dll文件。如果这些文件已存在于您的项目中，您可能会看到GUID冲突。在我们的测试用例中，它不会导致任何问题，但如果您遇到问题，请填写问题：问题。从项目中删除重复的dll可能会解决冲突。

GUID [eb9c83041c7a89c46bb6e20eab4484df] for asset 'Packages/com.signal-loop.unitycodemcpserver/Editor/Bin/Microsoft.CodeAnalysis.CSharp.dll' conflicts with:
  '[Path to dll file in your project]/Microsoft.CodeAnalysis.CSharp.dll' (current owner)
We can't assign a new GUID because the asset is in an immutable folder. The asset will be ignored.

许可证

麻省理工学院