🚀 Unity MCP 与 Ollama 集成使用指南

本指南将详细介绍如何在 Unity 中借助 MCP 协议，通过 Ollama 集成本地大语言模型（LLMs）。利用此集成，你可以轻松实现创建场景对象、附加脚本等功能。文档会全面涵盖安装步骤、配置说明、使用方法、状态指示、性能考量、故障排除等内容。

🚀 快速开始

本指南将带你完成在 Unity 中使用 MCP 协议通过 Ollama 集成本地大语言模型（LLMs）的过程。

✨ 主要特性

• 支持在 Unity 中通过 MCP 协议与 Ollama 集成，实现本地大语言模型的调用。
• 可以根据自然语言提示创建场景对象、附加脚本等。
• 提供状态指示，方便了解各组件的连接状态。

📦 安装指南

系统要求

• Python：3.10 或更高版本
• Ollama：需从ollama.ai下载并安装
• Unity Editor：确保已正确安装

显式设置说明

创建项目目录

mkdir C:\PythonMCP
cd C:\PythonMCP

克隆代码仓库

git clone https://github.com/ZundamonnoVRChatkaisetu/unity-mcp-ollama.git

复制 Python 文件夹

copy unity-mcp-ollama\Python .

创建虚拟环境

python -m venv venv

激活虚拟环境

venv\Scripts\activate

安装依赖项

cd Python
pip install -e .

启动服务器

python server.py

💻 使用示例

基础用法

在聊天界面输入以下示例提示，即可与系统进行交互：

• "创建一个红色方块位于位置(0, 1, 0)"
• "添加一个球体到场景中并应用蓝色材质"
• "列出当前场景中的所有物体"
• "编写一个简单的移动脚本并将其附加到方块上"

📚 详细文档

状态指示

组件状态说明

• Python 服务器状态：

  • 绿色：已连接
  • 黄色：连接异常
  • 红色：未连接

• Unity 桥接状态：

  • 运行中：表示 Unity 正在监听连接请求
  • 停止：表示 Unity 的 socket 服务器未运行

• Ollama 状态：

  • 已连接：成功连接到 Ollama 服务器
  • 未连接：无法连接到 Ollama

性能考量

本地 LLM 性能依赖硬件配置：

• 使用deepseek - r1:14b模型推荐至少 12GB 显存
• 使用gemma3:12b模型推荐至少 10GB 显存
• CPU - only 模式可行但速度会显著降低

故障排除

常见问题

1. Python 服务器未连接

   • 确保 Python 服务器正在运行（执行python server.py）
   • 检查 Python 控制台是否有错误信息
   • 确认 Unity 桥接已启动

2. 找不到 Unity MCP 菜单

   • 确保 Editor 脚本已正确导入项目
   • 检查 Unity 控制台是否有错误提示
   • 重启 Unity 尝试解决

3. Ollama 连接问题

   • 确保 Ollama 服务正在运行（通过ollama serve检查）
   • 核对模型是否已正确加载
   • 查看防火墙设置，确认 11434 端口未被阻止

4. MCP 命令执行失败

   • 检查 Python 控制台获取详细错误信息
   • 确保 Unity 桥接正常运行
   • 确认提示指令清晰明确

📄 许可证

本项目遵循 MIT 许可证。

致谢

感谢以下项目的贡献：

• 基于Justin P. Barnett 的 unity - mcp
• 使用Ollama实现本地 LLM 集成