关键词

UnityAI游戏开发编辑器扩展自动化

Unity MCP 服务器使用说明

项目简介

Unity MCP服务器是一个基于Model Context Protocol (MCP) 构建的后端应用，旨在连接外部AI客户端（如Claude Desktop或Cursor）与Unity编辑器。它允许AI客户端通过标准协议调用Unity编辑器内的各种功能，实现对Unity项目的智能控制、信息查询和自动化操作。

主要功能点

  • 场景管理: 获取当前场景信息、打开/保存场景、创建新场景、切换场景。
  • 对象管理: 获取对象属性、创建/修改/删除对象、根据名称或标签查找对象、获取场景层级、选择对象。
  • 脚本管理: 查看/创建/更新脚本文件、列出文件夹中的脚本、将脚本组件附加到对象。
  • 资源管理: 导入外部资源、实例化Prefab、从对象创建Prefab、将Prefab实例的修改应用回Prefab资源、列出项目中的资源。
  • 材质管理: 设置对象的材质和颜色。
  • 编辑器控制: 执行撤销/重做、进入/暂停/停止播放模式、执行项目Build、读取Unity控制台日志、获取可用编辑器命令列表。

安装步骤

  1. 将仓库内容导入Unity项目: 将此仓库的内容作为Unity Editor Extension导入到您的Unity项目中。通常，这可以通过Unity的Package Manager（如果发布为包）或直接将Editor文件夹复制到项目的Assets目录下完成。
  2. 启动Unity Editor: 确保Unity Editor正在运行，并且加载了包含Unity MCP Server扩展的项目。Unity MCP Bridge (UnityEditor/UnityMCPBridge.cs) 会在Editor启动时自动尝试初始化并监听端口 '6400'。
  3. 确认Python服务器脚本存在: 这个MCP服务器的实际工作由一个Python脚本 ('Python/server.py') 完成，它通过TCP连接与运行在Unity Editor中的C# Bridge通信。请确保'server.py'文件存在于您Unity项目下的'Assets/unity-mcp/Python' 或 Package Cache 中。
  4. 配置MCP客户端: 您需要配置您的MCP客户端（如Claude Desktop, Cursor等），告知它如何启动并连接到这个Unity MCP服务器。

服务器配置 (针对MCP客户端)

MCP客户端需要知道如何启动MCP服务器进程。Unity MCP服务器（Python部分）通常通过命令行启动。您需要在MCP客户端的配置文件中添加一个服务器条目，指定启动服务器的命令和参数。

典型的MCP客户端配置格式 (JSON):

{
  "mcpServers": {
    "unityMCP": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/unity-mcp/Python", // <--- 这里需要指向您的 server.py 所在的 Python 文件夹的绝对路径
        "run",
        "server.py"
      ]
    }
    // 您可能还配置了其他MCP服务器...
  }
}
  • '"unityMCP"': 这是提供给客户端识别服务器的名称，您可以根据需要修改（但通常建议保持一致）。
  • '"command"': 启动MCP服务器进程的命令。这里使用了 'uv' (a modern Python package installer and runner) 来运行 Python 脚本。请确保您的系统已安装 'uv' 或 Python，并能通过命令行执行。
  • '"args"': 传递给 'command' 的参数列表。
    • '"--directory", "/path/to/your/unity-mcp/Python"': 指定'uv'在哪个目录执行命令。这是最关键的配置项，您需要将 '/path/to/your/unity-mcp/Python' 替换为您的Unity项目中实际包含 'server.py' 文件的 'Python' 文件夹的绝对路径。这个路径可以通过Unity Editor中的 "Window/Unity MCP" 窗口找到或手动查找。
    • '"run", "server.py"': 告诉'uv'运行'Python'目录下的'server.py'脚本。

重要提示:

  • 请根据您实际安装'unity-mcp'的路径替换 '/path/to/your/unity-mcp/Python'。
  • 确保您的系统中安装了Python环境和 'uv'。
  • Unity Editor和Unity MCP Bridge (C#) 必须处于运行状态，Python MCP服务器才能连接到它。Python服务器会尝试连接到Unity Bridge监听的端口 ('6400')。

基本使用方法

  1. 启动Unity Editor 并加载您的项目。
  2. 启动MCP客户端。如果配置正确，客户端会尝试启动并连接到Unity MCP服务器（即'server.py'脚本）。
  3. 一旦连接成功，您就可以在MCP客户端中通过自然语言或工具调用来与Unity Editor交互，例如：
    • 询问当前场景中有哪些对象。
    • 请求创建一个立方体对象并放置在特定位置。
    • 让AI编写一个简单的Unity脚本并附加到一个对象上。
    • 执行Unity Editor的Build操作。
    • 读取控制台的错误日志。

参考MCP客户端提供的界面和能力列表（会显示Unity MCP服务器暴露的工具和Prompt）来了解具体可用的操作。

信息

分类

桌面与硬件

访问项目