Realvirtual MCP

realvirtual MCP服务器（Python）

Python MCP桥将AI代理连接到任何Unity项目，包括数字双胞胎、机器人和工业自动化。

该服务器通过WebSocket将AI代理（Claude Desktop、Claude Code、Cursor等）与Unity编辑器连接起来。Unity使用C#定义MCP工具 [McpTool] 属性。此服务器会自动发现它们并将其作为标准公开 主控程序 工具。

你永远不需要碰这个代码

与您编辑Python以添加工具的其他MCP服务器不同，此服务器是 透明网桥所有工具都是在Unity中的C#中使用简单的属性定义的：

[McpTool("Spawn an enemy")]
public static string SpawnEnemy([McpParam("Prefab name")] string prefab) { ... }

Python服务器在Unity重新编译后会自动发现新工具。没有Python更改，没有服务器重启，没有注册。请参阅 Unity MCP软件包 了解如何创建自定义工具。

AI Agent (Claude Desktop / Claude Code / Cursor)
    |
    | MCP Protocol (stdio or SSE)
    v
This Python Server (FastMCP)
    |
    | WebSocket (JSON, Port 18711)
    v
Unity Editor (C# Package)  -->  github.com/game4automation/io.realvirtual.mcp

独立

此存储库附带 嵌入式Python 3.12运行时 并且所有依赖项都已预先安装。不需要Python系统。

python/              Embedded Python 3.12 (Windows x64)
Lib/                 Pre-installed packages (mcp, websockets, etc.)
unity_mcp_server.py  The MCP server
start.bat            One-click launcher
requirements.txt     Dependency list (for reference)

快速开始

自动设置（通过Unity——推荐）

这 Unity MCP软件包 可以自动克隆和配置此服务器：

1. 通过包管理器安装Unity包（git URL: https://github.com/game4automation/io.realvirtual.mcp.git)
2. 点击 齿轮图标 在Unity MCP工具栏中
3. 点击 克隆Python服务器 --这运行 git clone 进入 Assets/StreamingAssets/realvirtual-MCP/
4. 点击 配置Claude --将MCP配置写入克劳德桌面和/或克劳德代码

要稍后更新，请单击 更新Python服务器（git pull） 在同一个弹出窗口中。

需求

• 版本控制系统 必须在PATH中安装并可用-- git-scm.com

手动设置

将存储库克隆到Unity项目的StreamingAssets文件夹中：

cd /Assets/StreamingAssets
git clone https://github.com/game4automation/realvirtual-MCP.git

稍后更新：

cd /Assets/StreamingAssets/realvirtual-MCP
git pull

手动配置

克劳德桌面版 (%APPDATA%/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "UnityMCP": {
      "command": "C:/.../python/python.exe",
      "args": ["C:/.../unity_mcp_server.py"],
      "env": { "PYTHONPATH": "C:/.../Lib" }
    }
  }
}

克劳德代码 (.mcp.json 在项目根目录中）：

{
  "mcpServers": {
    "UnityMCP": {
      "command": "C:/.../python/python.exe",
      "args": ["C:/.../unity_mcp_server.py"],
      "env": { "PYTHONPATH": "C:/.../Lib" }
    }
  }
}

替换 C:/... 与您的实际路径 StreamingAssets/realvirtual-MCP/ 目录。

手动运行

start.bat

或者使用明确的选项：

python/python.exe unity_mcp_server.py --mode stdio
python/python.exe unity_mcp_server.py --mode sse --http-port 8080
python/python.exe unity_mcp_server.py --ws-port 18712

命令行选项

--mode stdio|sse       Server mode (default: stdio)
--ws-port PORT         Unity WebSocket port (default: auto-discover)
--http-port PORT       HTTP port for SSE mode (default: 8080)
--project-path PATH    Connect to specific Unity instance
--verbose              Enable verbose logging

运作原理

连接生命周期

1. 初创公司 -从缓存加载工具模式以实现即时可用性
2. 发现 -通过WebSocket连接到Unity，发送 __discover__ 获取所有工具
3. 注册 -为每个发现的Unity工具创建FastMCP工具处理程序
4. 转发 -通过以下方式将MCP工具调用路由到Unity __call__ 命令
5. 看门狗 -后台任务监控连接，Unity域重新加载后自动重新连接

状态机

在...期间 给重新装入 和 重新连接，工具调用在重新连接后会被缓冲和重放（最多30秒TTL，100条消息限制）。

多实例支持

当多个Unity实例正在运行时，服务器会通过中的状态文件发现它们 ~/.unity-mcp/.使用 --project-path 针对特定实例。

Unity窗口唤醒

团结受阻 EditorApplication.update 当未聚焦时，频率为~2Hz。服务器使用 PostMessageW(WM_NULL) 在每次工具调用之前唤醒Unity的消息循环，确保响应式执行而不会窃取焦点。

WebSocket协议

服务器与Unity通信 ws://127.0.0.1:18711/mcp.

发现：

{"command": "__discover__"}
// Response: {"tools": [...], "schema_version": "1.0.0"}

工具调用：

{"command": "__call__", "tool": "sim_play", "arguments": {}}
// Response: {"result": {"status": "playing"}}

心跳：

{"command": "__heartbeat__"}
// Response: {"status": "ok", "tools_count": 65}

身份验证（可选）：

{"command": "__auth__", "token": "..."}
// Response: {"status": "ok"}

可用工具

工具是从Unity自动发现的。确切的设置取决于安装了哪些Unity软件包：

\*需要 realvirtual Unity框架。

两个内置管理工具始终可用：

• unity_status -连接状态和工具计数
• unity_reconnect -强制重新连接和重新发现工具

使用自己的Python

如果你更喜欢Python而不是嵌入式系统：

pip install -r requirements.txt
python unity_mcp_server.py --mode stdio

要求：Python 3.10+， websockets>=12.0, mcp>=1.8.0

故障排除

服务器无法连接到Unity

• 确保Unity编辑器与 MCP包 安装
• 检查端口18711是否未被防火墙阻止
• 验证MCP WebSocket服务器是否正在运行（Unity工具栏中的大脑图标）

“python.exe被防病毒软件阻止”

• 为嵌入式添加例外 python/python.exe 在您的防病毒软件中
• 或者使用您的系统Python安装

未发现工具

• 检查Unity控制台是否存在编译错误
• 使用 unity_reconnect 强制重新发现

调试日志

• 奔跑 --verbose 用于详细控制台输出的标志
• 调试日志始终写入 %TEMP%/realvirtual-mcp/mcp_debug.log

Unity套餐

这种集成的C#Unity方面：

****

通过Unity包管理器>从git URL添加包进行安装。

支持

此服务器已提供 按原样 不包括任何支持或服务。

对于商业客户 realvirtual，我们提供专业服务 数字孪生发展, 虚拟调试，以及 LLM/AI代理集成.联系我们https://realvirtual.io了解详情。

许可证

麻省理工学院许可证 - 版权所有 (c) 2026 realvirtual GmbH

看 许可证 全文。

链接

• 网站：https://realvirtual.io
• 文档：https://doc.realvirtual.io/extensions/mcp-server
• Unity MCP包：https://github.com/game4automation/io.realvirtual.mcp
• Unity资产存储（MCP服务器）：https://assetstore.unity.com/preview/361912/1260684
• Unity资产商店（初学者）：https://assetstore.unity.com/packages/tools/integration/realvirtual-io-digital-twin-starter-6-303030
• Unity资产商店（专业版）：https://assetstore.unity.com/packages/tools/integration/realvirtual-io-digital-twin-professional-6-301340