Unity MCP ✨

使用大语言模型（LLMs）创建你的Unity应用！

Unity MCP 充当桥梁，允许AI助手（如Claude、Cursor）通过本地 MCP（模型上下文协议）客户端 直接与你的Unity编辑器进行交互。为你的LLM提供工具来管理资源、控制场景、编辑脚本，并在Unity中自动化任务。

💬 加入我们的社区

Discord

获取帮助、分享想法，并与其他Unity MCP开发者合作！

主要功能 🚀

• 🗣️ 自然语言控制： 指示你的LLM执行Unity任务。
• 🛠️ 强大的工具： 管理资源、场景、材质、脚本和编辑器功能。
• 🤖 自动化： 自动化重复的Unity工作流程。
• 🧩 可扩展性： 设计为与各种MCP客户端兼容。

工作原理 🤔

Unity MCP通过两个组件连接你的工具：

1. Unity MCP 桥接器： 一个在编辑器内运行的Unity包。（通过包管理器安装）。
2. Unity MCP 服务器： 一个本地运行的Python服务器，在Unity桥接器和你的MCP客户端之间进行通信。（手动安装）。

流程： [你的LLM通过MCP客户端] <-> [Unity MCP服务器（Python）] <-> [Unity MCP桥接器（Unity编辑器）]

安装 ⚙️

注意： 随着我们更新包，安装过程也在不断改进。如果遇到问题，请随时回来查看。

先决条件

• Git CLI： 用于克隆服务器代码。下载 Git

• Python： 版本3.12或更高。下载 Python

• Unity Hub & 编辑器： 版本2020.3 LTS或更高。下载 Unity

• uv（Python包管理器）：

  pip install uv
  # 或参见：https://docs.astral.sh/uv/getting-started/installation/
  

• MCP客户端：

  • Claude Desktop
  • Claude Code
  • Cursor
  • Visual Studio Code Copilot
  • （其他客户端可能需要手动配置）
• [可选] Roslyn 用于高级脚本验证

  对于严格的验证级别，捕获未定义的命名空间、类型和方法：

  方法1：NuGet for Unity（推荐）

  1. 安装 NuGetForUnity
  2. 转到 Window > NuGet Package Manager
  3. 搜索 Microsoft.CodeAnalysis.CSharp 并安装该包
  4. 转到 Player Settings > Scripting Define Symbols
  5. 添加 USE_ROSLYN
  6. 重启Unity

  方法2：手动DLL安装

  1. 从 NuGet 下载 Microsoft.CodeAnalysis.CSharp.dll 及其依赖项
  2. 将DLL放置在 Assets/Plugins/ 文件夹中
  3. 确保.NET兼容性设置正确
  4. 添加 USE_ROSLYN 到 Scripting Define Symbols
  5. 重启Unity

  注意： 如果没有Roslyn，脚本验证将回退到基本的结构检查。Roslyn启用了完整的C#编译器诊断，并提供精确的错误报告。

第一步：安装Unity包（桥接器）

1. 打开你的Unity项目。
2. 转到 Window > Package Manager。
3. 点击 + -> Add package from git URL...。
4. 输入：

   https://github.com/justinpbarnett/unity-mcp.git?path=/UnityMcpBridge
   

5. 点击 Add。
6. MCP服务器应该会在此过程中自动安装到你的机器上。

第二步：配置你的MCP客户端

将你的MCP客户端（Claude、Cursor等）连接到你在第一步中安装的Python服务器。

选项A：自动配置（推荐用于Claude/Cursor/VSC Copilot）

1. 在Unity中，转到 Window > Unity MCP。
2. 点击你使用的IDE上的 Auto Configure。
3. 寻找绿色状态指示器 🟢 和“已连接”。（这将尝试自动修改MCP客户端的配置文件）。

选项B：手动配置

如果自动配置失败或你使用不同的客户端：

1. 找到你的MCP客户端的配置文件。（查看客户端文档）。
   • Claude 示例（macOS）： ~/Library/Application Support/Claude/claude_desktop_config.json
   • Claude 示例（Windows）： %APPDATA%\Claude\claude_desktop_config.json
2. 编辑文件 以添加/更新 mcpServers 部分，使用第一步中的确切路径。

{
  "mcpServers": {
    "UnityMCP": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "C:\\Users\\YOUR_USERNAME\\AppData\\Local\\Programs\\UnityMCP\\UnityMcpServer\\src",
        "server.py"
      ]
    }
    // ... 其他服务器可能在这里 ...
  }
}

{
  "mcpServers": {
    "UnityMCP": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/usr/local/bin/UnityMCP/UnityMcpServer/src",
        "server.py"
      ]
    }
    // ... 其他服务器可能在这里 ...
  }
}

{
  "mcpServers": {
    "UnityMCP": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/home/YOUR_USERNAME/bin/UnityMCP/UnityMcpServer/src",
        "server.py"
      ]
    }
    // ... 其他服务器可能在这里 ...
  }
}

claude mcp add UnityMCP -- uv --directory /[PATH_TO]/UnityMCP/UnityMcpServer/src run server.py

claude mcp add UnityMCP -- "C:/Users/USERNAME/AppData/Roaming/Python/Python313/Scripts/uv.exe" --directory "C:/Users/USERNAME/AppData/Local/Programs/UnityMCP/UnityMcpServer/src" run server.py

使用 ▶️

1. 打开你的Unity项目。 Unity MCP桥接器（包）应该会自动连接。通过 Window > Unity MCP 检查状态。

2. 启动你的MCP客户端（Claude、Cursor等）。它应该会自动启动Unity MCP服务器（Python），使用安装步骤3中的配置。

3. 开始交互！ Unity工具现在应该可以在你的MCP客户端中使用。

   示例提示：创建一个3D玩家控制器，创建一个黄色的太阳和桥梁，创建一个酷炫的着色器并将其应用到立方体上。

未来开发计划（除了PR） 📝

🔴 高优先级

• [ ] 资源生成改进 - 增强服务器请求处理和资源管道优化
• [ ] 代码生成增强 - 提高生成代码的质量和错误处理
• [ ] 健壮的错误处理 - 全面的错误消息、恢复机制和优雅降级
• [ ] 远程连接支持 - 实现Unity主机和MCP服务器之间的无缝远程连接
• [ ] 文档扩展 - 完成自定义工具创建教程和API参考

🟡 中优先级

• [ ] 自定义工具创建GUI - 为用户创建和配置自己的MCP工具提供可视化界面
• [ ] 高级日志系统 - 带有过滤、导出和调试功能的日志系统

🟢 低优先级

• [ ] 移动平台支持 - 扩展工具集以支持移动开发工作流程和平台特定功能
• [ ] 更简单的工具设置
• [ ] 插件市场 - 社区驱动的工具共享和分发平台