Blender Pose MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Blender Pose MCP Set the head bone rotation to 30 degrees on X."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Blender Pose MCP
一个极简、专用的 Blender Pose MCP,只操作当前场景中唯一一个已存在的 Armature 的 Pose。它不提供建模、材质、权重、骨骼编辑、对象创建/删除或任意 Python 执行能力。
Codex -> MCP stdio server -> 127.0.0.1:8766 JSON/TCP -> Blender add-on组件
blender_pose_bridge/:安装到 Blender 的独立 Add-on。启用后自动监听127.0.0.1:8766,禁用时关闭 socket、后台线程和 timer。blender_pose_mcp/:在uv管理的 Python 环境中运行的官方 MCP Python SDK v2 stdio Server。reference/main.py:原始且不修改的SMPLest-X Loader参考实现。
Bridge 网络线程只收发 JSON 并把请求放入线程安全队列。所有 bpy 操作由
bpy.app.timers 回到 Blender 主线程执行。场景中没有 Armature 或存在多个
Armature 时,调用会明确失败;多个对象时错误中包含全部 Armature 名称。
Related MCP server: blender-mcp
安装 Blender Add-on
可直接压缩 blender_pose_bridge 文件夹:
ditto -c -k --sequesterRsrc --keepParent blender_pose_bridge blender_pose_bridge.zip在 Blender 中打开 Edit > Preferences > Add-ons > Install from Disk,选择
blender_pose_bridge.zip,然后启用 Blender Pose Bridge。它与原有
SMPLest-X Loader (Simplified) 使用不同的类名、Panel、PropertyGroup 和
Operator ID,可以同时启用。3D View 侧栏的 Pose Bridge 页会显示在线状态。
安装 MCP Python 环境(macOS + uv)
MCP Server 要在普通 Python 中运行,不使用 Blender 自带 Python。先安装 uv,
再同步项目环境:
brew install uv
uv sync其他安装方式见 uv 官方安装说明。
uv sync 会依据 pyproject.toml 创建 .venv、解析依赖并以 editable 模式安装
当前项目。依赖只有官方 mcp 包及其运行时依赖;不需要 PyTorch、Transformers、
sentence-transformers、LaBSE、Ollama、embedding/vector database 或本地 LLM,
也不需要手动激活虚拟环境。
添加到 Codex
把 /ABSOLUTE/PATH/blender-pose-tools 替换成仓库绝对路径:
codex mcp add blender-pose -- uv --directory /ABSOLUTE/PATH/blender-pose-tools run blender-pose-mcp也可以写入 ~/.codex/config.toml 或可信项目的 .codex/config.toml:
[mcp_servers.blender-pose]
command = "uv"
args = ["--directory", "/ABSOLUTE/PATH/blender-pose-tools", "run", "blender-pose-mcp"]
cwd = "/ABSOLUTE/PATH/blender-pose-tools"
startup_timeout_sec = 10
tool_timeout_sec = 60重启 Codex 后使用 /mcp,应看到 blender-pose 和下列工具:ping、
get_rig、get_pose、set_bone_pose、set_pose_batch、apply_smplx_pose、
reset_pose、undo、get_viewport、save_blend。
工具语义
set_bone_pose/set_pose_batch接收本地 Pose Bone 的 XYZ degree。absolute替换当前本地 rotation,delta将增量 quaternion 右乘到当前本地 rotation;两者都不会重置其他骨骼。一个 batch 只创建一个 Blender Undo step。apply_smplx_pose会像原脚本一样先重置 Pose,再完整导入 SMPL-X JSON。 它保留原脚本的 rotvec、Root、Hand、坐标系和matrix_localbasis 转换。reset_pose当前只接受{"scope": "all"},用matrix_basis恢复基础 Pose, 不修改 Rest Pose。get_pose返回每根骨骼的语义、父级、本地旋转,以及 Pose 后 head/tail 在 Armature 空间和世界空间中的坐标。get_viewport一次返回上述结构化 Pose 快照和固定的前、左、右、后四张正交 视图。PNG 既以内嵌 MCP 图片交给 Codex 视觉检查,也在系统临时目录中提供路径; 图片保持原纵横比且高度不超过 768px,截图完成后会恢复原来的视口方向,不污染 项目。save_blend永不自动调用。未曾保存过、没有文件路径的项目会返回错误。
完整 SMPL-X 参数形状与原脚本一致,例如:
{
"body_root_pose": [[0.0, 0.0, 0.0]],
"body_pose": [[0.0, 0.0, 0.0]],
"lhand_pose": [],
"rhand_pose": []
}测试
普通 Python 自动测试覆盖 tools/list、ping、参数校验、Blender 离线、无 Armature 和多个 Armature 错误:
uv run python -m unittest discover -s tests -p 'test_*.py' -v真实 Blender 后台测试只创建测试 Armature,不创建或修改 Mesh:
blender --background --factory-startup --python tests/blender_automated_test.py
blender --background --factory-startup --python tests/blender_conversion_test.py
blender --background --factory-startup --python tests/blender_tcp_test.py可选的前台 VIEW_3D 截图测试会短暂打开 Blender、删除测试 PNG 后自动退出:
blender --factory-startup --python-exit-code 1 --python tests/blender_viewport_test.py手动 smoke test:在一个包含唯一目标 Armature(且含 head)的 Blender 中,
从 Text Editor 打开并运行 tests/blender_smoke_test.py。它依次执行 ping、
get_rig、get_pose、修改 head、undo、reset。最后一步会重置当前 Pose,但脚本
不会保存 .blend。
卸载
codex mcp remove blender-pose然后在 Blender Preferences 中禁用并移除 Blender Pose Bridge。需要彻底删除
Python 环境时,可删除仓库内 .venv/;项目或 .blend 不受影响。
原始 main.py 与转换复用
不需要修改 reference/main.py。blender_pose_bridge/smplx.py 直接保留其
ROOT_BONE、BODY_BONES、HAND_BONES、BODY_OFFSETS、
rotvec_to_quaternion、set_bone_rot、Root 180° 修正、Hand rotvec 符号反转、
SMPL-X 到 Blender 的 X 轴 90° quaternion 转换,以及
bone.matrix_local.to_quaternion() basis 转换。交互式 degree 接口是独立逻辑,
不会改变完整 JSON 导入行为。
Available Tools
10 toolsapply_smplx_poseC
Reset then import one full SMPL-X pose using the verified main.py rules.
Inputs: body_pose, lhand_pose, rhand_pose, body_root_pose. Returns: object
get_poseA
Read all current local Pose Bone rotations in degrees and quaternions.
Inputs: no named parameters. Returns: object
get_rigA
Read the existing Armature hierarchy, rest basis, constraints, and roles.
Inputs: no named parameters. Returns: object
get_viewportA
Return structured Pose data and fixed front/left/right/back PNG views.
Inputs: no named parameters.
pingA
Test Codex -> MCP -> Blender and report file, version, and Armature.
Inputs: no named parameters. Returns: object
reset_poseA
Reset the existing Armature to its base pose. Only scope='all' is valid.
Inputs: scope. Returns: object
save_blendA
Save the current .blend; call only after an explicit user save request.
Inputs: no named parameters. Returns: object
set_bone_poseA
Set or locally delta-rotate one Pose Bone without resetting other bones.
Inputs: bone (required), rotation_degrees (required), mode. Returns: object
set_pose_batchA
Apply multiple local Pose Bone edits together as one Blender undo step.
Inputs: changes (required). Returns: object
undoA
Use Blender's undo system to undo the most recent operation.
Inputs: no named parameters. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool has a clearly distinct function: health check, rig structure read, pose read, single/batch edits, SMPL-X import, reset, undo, viewport, and save. The only nearby pairs are separated by scope or output, so an agent should not misselect.
Tool names uniformly use lowercase snake_case and mostly follow a verb-first pattern like get_*, set_*, reset_pose, and save_blend. The single-word ping and undo are minor deviations from the verb_noun convention, so the set is consistent but not perfectly patterned.
With 10 tools, the set is well-scoped for a pose-editing assistant: read, edit, batch, apply/reset, undo, view, and save operations are each represented exactly once. No tool feels redundant or unnecessary.
The core pose workflow is well covered: query state, mutate individual bones, batch changes, apply a full SMPL-X pose, reset, undo, render viewport, and save. The main gaps are generic custom pose import/export and rig constraint editing, but these are not necessarily required for the server's stated posing purpose.
Related MCP Connectors
MCP server for progressive tool usage at any scale (see https://klavis.ai)
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
MCP Server for Slima - AI Writing IDE for Novel Authors with AI Beta Reader.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceAn MCP server that enables AI agents to control Blender through natural language for 3D scene creation, animation, and rendering. It provides over 550 actions and direct Python execution via a bridge to a live local Blender session.7MIT
- AlicenseCqualityDmaintenanceMCP server that enables AI to control Blender 3D, providing 175 typed tools for objects, materials, animation, compositing, and more via the Model Context Protocol.1003MIT
- AlicenseAqualityDmaintenanceMCP server for Blender that connects to the official Blender Lab add-on, exposing 27 tools for scene manipulation, object editing, materials, rendering, and Python execution through the add-on's actual wire protocol.271MIT
- AlicenseBqualityCmaintenanceAn MCP server that builds and modifies Blender .blend files, supporting both headless generation and live interaction with an open Blender window.16MIT