故障排除

服务器无法启动

  • 检查 Unity Console 中的 [MCP] 日志条目
  • 确保端口 18711 未被防火墙或其他应用程序阻止
  • 通过工具栏弹窗切换 Debug 模式以获取详细日志
  • 尝试在设置弹窗中点击 Restart Python Server

工具未被发现

  • 确保方法带有 [McpTool] 属性且为 public static string
  • 检查 Unity Console 中的编译错误——工具仅在成功编译后注册
  • 在工具栏弹窗中点击 Refresh 强制重新发现
  • 验证工具类所在程序集是否引用了 realvirtual.MCP

连接问题

  • 有客户端连接时大脑图标应为 绿色
  • 黄色 表示服务器正在运行但尚无客户端连接
  • 检查您的 MCP客户端配置是否指向正确的 Python 服务器路径
  • 确保 git 已安装并在 PATH 中可用

播放模式期间超时

  • Unity在播放模式期间限制编辑器更新——工具调用可能变慢
  • component_set 操作在播放模式期间可能无法工作
  • 如果 Unity主线程忙于仿真，component_get 可能超时
  • 建议在执行编辑器操作之前停止仿真

Python 服务器问题

  • 点击 Update Python Server (git pull) 获取最新版本
  • 点击 Open MCPFolder 查看 Python 服务器文件
  • Python 服务器包含内置的 Python 3.12 运行时——无需系统 Python
  • 检查 Python 服务器控制台输出以查看连接错误

端口冲突

MCPServer 默认使用端口 18711。如果端口忙，它会自动递增以找到空闲端口。实际端口显示在工具栏弹窗中。确保您的 MCP客户端配置与显示的端口匹配。

多实例设置

每个 Unity实例获得一个唯一的实例哈希（在工具栏中显示为 #xxxxxxxx）。同时运行多个 Unity项目时，每个实例在不同的端口上运行自己的 MCPServer。Python 服务器使用实例哈希连接到正确的 Unity实例。

realvirtual.io 中文文档 查看原文 →