让任何 MCP 客户端（Claude Code / Codex / Hermes 等）在 MotionBuilder 内远程执行 Python 代码。 兼容 MoBu 2019（Python 2.7） 与 MoBu 2024（Python 3.10），同一份监听器代码双版本通用。 为 MetaHuman 面部实时预览项目（OpenRigLogic）而建。
MCP 客户端 (Claude Code / Codex / Hermes ...)
↕ stdio (MCP 协议)
server/mobu_mcp_server.py ← MCP 服务器（外部 Python 3.10+ 运行，需 pip install mcp）
↕ TCP 127.0.0.1:4600 (JSON 行协议)
mobu_side/mobu_command_server.py ← MoBu 内监听器（pyfbsdk，Py2/Py3 双兼容）
监听器的 socket 线程只做收发，代码统一排队到 FBSystem().OnUIIdle 回调，
在 MoBu 主线程执行（pyfbsdk 场景操作不允许跨线程）。
每次启动 MotionBuilder 后执行一次（或配置开机自启）。
在 Python Editor 里运行：
exec(open(r"D:/Code/MoBuMCP/mobu_side/mobu_command_server.py", encoding="utf-8").read())在 Python Editor 里运行：
execfile(r"D:/Code/MoBuMCP/mobu_side/mobu_command_server.py")⚠ Py2 下不要用
exec(io.open(...).read())：unicode 源码 + coding 声明会报SyntaxError: encoding declaration in Unicode string。execfile按字节读，无此问题。
[MoBu MCP] 监听器已启动 127.0.0.1:4600（Py2，主线程执行，OnUIIdle 调度） ← 2019
[MoBu MCP] 监听器已启动 127.0.0.1:4600（Py3，主线程执行，OnUIIdle 调度） ← 2024
把 mobu_command_server.py 复制到对应版本的启动脚本目录：
C:\Users\<用户>\Documents\MB\2019\config\PythonStartup\
C:\Users\<用户>\Documents\MB\2024\config\PythonStartup\
- 停止：在 Python Editor 里调用
MOBU_MCP_STOP() - 热重载（改了监听器代码后）：直接再执行一遍上面的启动命令即可。 内置单例机制会自动停掉旧实例、等待端口释放、启动新实例，无需重启 MoBu。
MCP 服务器脚本 server/mobu_mcp_server.py 需要 Python 3.10+ 且安装了 mcp 包：
pip install mcp以下 <python> 均指装有 mcp 包的 Python 3 解释器路径。
命令行注册（推荐，用户级全局可用）：
claude mcp add mobu-mcp --scope user -- <python> D:/Code/MoBuMCP/server/mobu_mcp_server.py或在项目根目录创建 .mcp.json（项目级，随仓库共享）：
{
"mcpServers": {
"mobu-mcp": {
"command": "<python>",
"args": ["D:/Code/MoBuMCP/server/mobu_mcp_server.py"]
}
}
}验证：在 Claude Code 里运行 /mcp，应看到 mobu-mcp 及 2 个工具；
或直接对话"检查 MotionBuilder 连接状态"。
编辑 ~/.codex/config.toml（Windows 为 C:\Users\<用户>\.codex\config.toml），添加：
[mcp_servers.mobu-mcp]
command = "<python>"
args = ["D:/Code/MoBuMCP/server/mobu_mcp_server.py"]重启 Codex 后生效。验证：codex mcp list 应列出 mobu-mcp。
config.yaml 中添加：
mcp_servers:
mobu-mcp:
enabled: true
command: C:/Users/dalaotian/AppData/Local/hermes/hermes-agent/venv/Scripts/python.exe
args:
- D:/Code/MoBuMCP/server/mobu_mcp_server.py⚠
command与args必须分离，把参数拼进 command 字符串会报 WinError 2。
验证：hermes mcp test mobu-mcp（应显示 2 个工具）。
| 工具 | 说明 |
|---|---|
mcp_run_python_code_in_mobu(python_code, main_function, timeout) |
在 MoBu 主线程执行 Python，返回入口函数结果（repr）+ stdout；异常回传完整 traceback |
mcp_mobu_status() |
探测 MoBu 监听器连通性与版本信息 |
- 先探版本再写代码：
mcp_mobu_status()返回mobu_version/python_version。 MoBu 2019 端执行的代码必须是 Py2 语法（无 f-string、print需from __future__或函数式调用）。 - 代码需定义一个入口函数（
main_function参数指定），其返回值的 repr 作为结果回传； 只写顶层语句拿不到返回值。 - 修改场景遵循：查询当前状态 → 执行修改 → 验证结果；复杂任务拆小步执行。
- 长任务会阻塞 MoBu UI（与在 Python Editor 里直接跑一样）；默认超时 30s，重操作调大
timeout。 - 超时 ≠ 取消：超时后任务仍在队列中，之后可能照常执行，勿盲目重试有副作用的操作。
请求: {"code": "def f():\n return 1", "main_function": "f", "timeout": 30}
成功: {"ok": true, "result": "1", "stdout": ""}
失败: {"ok": false, "error": "<traceback>", "stdout": "..."}pyfbsdk 的场景操作不允许跨线程。监听器的 socket 线程只做收发，
代码统一排队到 FBSystem().OnUIIdle 回调，在 MoBu 主线程执行。含义：
- MoBu 空闲时任务几乎即时执行；播放/渲染中会延迟到空闲
- 长任务会阻塞 MoBu UI
- 默认超时 30s，重操作调大
timeout参数
queue/Queue、builtins/__builtin__、StringIO按版本分支导入- Py2 下
result/stdout/error统一经_to_text()解码为 unicode 再序列化——否则含中文的字节 str 遇json.dumps(ensure_ascii=False)会抛UnicodeDecodeError杀死处理线程（曾是实测复现的严重 bug） - Py2 下含中文的报错消息一律用
u""前缀构造 socket.error捕获两版通吃（Py2 无ConnectionError）- Windows 上用
SO_EXCLUSIVEADDRUSE防止多实例静默共存同一端口
| 现象 | 处理 |
|---|---|
无法连接 MotionBuilder（127.0.0.1:4600） |
MoBu 未启动，或监听器未运行——回到第一步 |
MoBu 端连接中断且未返回响应 |
监听器处理线程崩溃（监听主循环通常仍存活），重试或在 MoBu 里重新 exec 启动脚本 |
执行超时 |
MoBu 正忙（播放/渲染/长任务）；注意任务仍在队列中，之后可能照常执行 |
| 端口 4600 被占用 | netstat -ano | findstr :4600 查 PID；若是残留 MoBu 进程则结束它。正常热重载已内置端口重试，无需手动处理 |
Py3 下遍历场景组件抛 UnicodeDecodeError |
场景里有 GBK 编码命名的组件（旧版 max/fbx 导入的中文名）——读 .Name 时套 try/except，与本桥接无关 |
- 2026-07：假监听器（同协议无 pyfbsdk）下通信层 4 项测试全过；
hermes mcp test mobu-mcp连接成功发现 2 工具。 - 2026-07-14 MoBu 2019（Py2.7.11）真机全链路：中文 print / 中文返回值 / 中文异常 traceback、错误入口函数名、非法 JSON 与非 dict 请求防护、 超时响应（UTF-8 编码正确）。
- 2026-07-14 MoBu 2024（Py3.10.8）真机全链路：上述全部 + f-string + pyfbsdk 场景操作（建立/查询/删除 Cube）+ 热重载（重复 exec 自动停旧启新）。