Unity MCP Server

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 ：通过路径执行菜单项（例如“文件/保存项目”）。

工作原理

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 中的精确路径。

视窗：

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

macOS：

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

Linux：

（替换 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 团队。