Unity MCP ✨

使用模型上下文协议将您的 Unity 编辑器连接到 LLM。

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

主要特点🚀

• **🗣️ 自然语言控制：**指导你的 LLM 执行 Unity 任务。

• **🛠️强大的工具：**管理资产、场景、材质、脚本和编辑器功能。

• **🤖 自动化：**自动化重复的 Unity 工作流程。

• **🧩 可扩展：**设计用于与各种 MCP 客户端协同工作。

您的法学硕士 (LLM) 可以使用以下功能：

• read_console ：从控制台获取消息或清除控制台。

• manage_script ：管理 C# 脚本（创建、读取、更新、删除）。

• manage_editor ：控制和查询编辑器的状态和设置。

• manage_scene ：管理场景（加载、保存、创建、获取层次结构等）。

• manage_asset ：执行资产操作（导入、创建、修改、删除等）。

• manage_gameobject ：管理GameObjects：创建、修改、删除、查找和组件操作。

• execute_menu_item ：通过路径执行菜单项（例如“文件/保存项目”）。

Related MCP server: 3D-MCP

工作原理

Unity MCP 使用两个组件连接您的工具：

1. **Unity MCP Bridge：**在编辑器内运行的 Unity 软件包。（通过软件包管理器安装）。

2. **Unity MCP 服务器：**一个本地运行的 Python 服务器，用于在 Unity Bridge 和 MCP 客户端之间进行通信。（手动安装）。

流程： [Your LLM via MCP Client] <-> [Unity MCP Server (Python)] <-> [Unity MCP Bridge (Unity Editor)]

安装⚙️

**注意：**随着软件包的更新，设置也会不断改进。如果您偶尔遇到问题，请回来查看。

先决条件

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

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

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

• uv（Python包管理器）：

  pip install uv
  # Or see: https://docs.astral.sh/uv/getting-started/installation/

• MCP 客户端：

  • 克劳德桌面

  • 光标

  • （其他人可能使用手动配置）

步骤 1：安装 Unity 包（Bridge）

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 服务器将自动安装到您的机器上。

步骤 2：配置您的 MCP 客户端

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

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

1. 在 Unity 中，转到Window > Unity MCP 。

2. 单击Auto Configure Claude或Auto Configure Cursor 。

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部分，使用步骤 1 中的精确路径。

视窗：

{
  "mcpServers": {
    "UnityMCP": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "C:\\Users\\YOUR_USERNAME\\AppData\\Local\\Programs\\UnityMCP\\UnityMcpServer\\src",
        "server.py"
      ]
    }
    // ... other servers might be here ...
  }
}

（记住替换 YOUR_USERNAME 并使用双反斜杠 \）

macOS：

{
  "mcpServers": {
    "UnityMCP": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/usr/local/bin/UnityMCP/UnityMcpServer/src",
        "server.py"
      ]
    }
    // ... other servers might be here ...
  }
}

（如果使用 ~/bin，请替换 YOUR_USERNAME）

Linux：

{
  "mcpServers": {
    "UnityMCP": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/home/YOUR_USERNAME/bin/UnityMCP/UnityMcpServer/src",
        "server.py"
      ]
    }
    // ... other servers might be here ...
  }
}

（替换 YOUR_USERNAME）

使用方法▶️

1. 打开你的 Unity 项目。Unity MCP Bridge（软件包）应该会自动连接。通过“窗口”>“Unity MCP”检查连接状态。

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

3. 互动！ Unity 工具现在应该可以在您的 MCP 客户端中使用。

   示例提示： Create a 3D player controller.

贡献🤝

帮助改进 Unity MCP！

1. 分叉主存储库。

2. 创建一个分支（ feature/your-idea或bugfix/your-fix ）。

3. 做出改变。

4. 提交（功能：添加很酷的新功能）。

5. 推动你的分支。

6. 针对主分支打开拉取请求。

故障排除❓

• Unity Bridge 未运行/连接：

  • 确保 Unity 编辑器已打开。

  • 检查状态窗口：窗口 > Unity MCP。

  • 重新启动 Unity。

• MCP 客户端未连接/服务器未启动：

  • **验证服务器路径：**仔细检查 MCP 客户端 JSON 配置中的 --directory 路径。它必须与您在安装步骤 1 中克隆 UnityMCP 存储库的位置完全匹配（例如，.../Programs/UnityMCP/UnityMcpServer/src）。

  • **验证 uv：**确保 uv 已安装并正常工作（pip show uv）。

  • **手动运行：**尝试直接从终端运行服务器以查看错误： # Navigate to the src directory first! cd /path/to/your/UnityMCP/UnityMcpServer/src uv run server.py

  • **权限（macOS/Linux）：**如果您将服务器安装在系统位置（例如 /usr/local/bin），请确保运行 MCP 客户端的用户有权执行 uv 并访问那里的文件。安装在 ~/bin 中可能更容易。

• 自动配置失败：

  • 使用手动配置步骤。自动配置可能缺少写入 MCP 客户端配置文件的权限。

还卡住吗？ 打开问题。

许可证📜

MIT 许可证。请参阅LICENSE文件。

联系👋

• X/Twitter： @justinpbarnett

致谢🙏

感谢贡献者和 Unity 团队。