Blender Animation MCP

An animation-specialized MCP server for Blender. It combines precise timeline/keyframe tools with rendered visual feedback, so a multimodal model can inspect what it animated instead of reasoning from transforms alone.

import_glb_asset loads textured or rigged GLB/glTF assets without flattening their hierarchy; inspect_rig exposes skeletons and bindings; and key_pose_bone provides a safer pose interface than raw RNA paths. Existing embedded animation clips are imported by Blender's glTF importer and included in visual review.

What it can see and control

• Render any exact frame and return it as MCP image content.
• Render a contact sheet sampled over the shot for fast visual review.
• Sample evaluated world transforms and bounding boxes across time.
• Inspect actions, F-curves, handles, interpolation, NLA strips, constraints, cameras, and markers.
• Insert/delete keys, change interpolation, control the timeline, and save the file.
• Import arbitrary .glb and .gltf assets with their hierarchy, materials, rigs, and animation clips.
• Inspect generated skeletons and key bones directly with local-space quaternions.
• Discover weighted limb-chain candidates and inspect their actual local axes.
• Probe bone deformation non-destructively before authoring poses.
• Create paw IK controls, key them in world space, and validate planted-foot sliding.

The contact sheet is made from actual scene renders. It is deliberately capped at 25 frames; for detailed review, call render_frame on suspicious frames. Animation is temporal, so no finite sample proves every in-between frame is correct—the intended workflow is contact sheet, targeted frames, numeric evaluation, then another visual pass.

Install

1. Zip the blender_addon directory (the zip must contain blender_addon/__init__.py) and install it from Edit > Preferences > Add-ons > Install from Disk. Enable Animation MCP Bridge.

2. The bridge starts automatically with Blender. Use Scene Properties > Animation MCP to see its status or stop/restart it.

3. Install this MCP package:

   pip install -e .
   

4. Add it to your MCP client configuration:

   {
     "mcpServers": {
       "blender-animation": {
         "command": "blender-animation-mcp",
         "env": {
           "BLENDER_MCP_HOST": "127.0.0.1",
           "BLENDER_MCP_PORT": "9876",
           "BLENDER_MCP_TOKEN": ""
         }
       }
     }
   }
   

For security, the bridge binds to localhost by default. If you configure a token in Blender, set the same BLENDER_MCP_TOKEN for the MCP process. Do not expose the port to an untrusted network.

Recommended model loop

1. inspect_scene and inspect_object_animation before editing. For a new GLB/glTF asset, call import_glb_asset first and inspect_rig if it is rigged.
2. Set keys and interpolation.
3. inspect_animation_visual across the whole shot.

For video-driven pose matching, call setup_video_reference with the source MP4, then use render_video_overlay for exact key poses or inspect_video_overlay for a contact sheet. Adjust video_frame_offset to align the Blender timeline with the useful interval of the reference before keying the rig. For unfamiliar generated rigs, run discover_limb_chains, inspect candidates with inspect_bone_axes, and confirm hinge behavior using probe_bone_deformation. Only then create paw controls with create_limb_ik; animate them through key_paw_pose and check contacts with validate_walk_cycle. 4. Use render_frame around contacts, extremes, and visible discontinuities. 5. Use evaluate_animation when exact spacing or world transforms matter. 6. Iterate, then save_blend.

Environment variables

BLENDER_MCP_HOST, BLENDER_MCP_PORT, BLENDER_MCP_TOKEN, and BLENDER_MCP_TIMEOUT configure the MCP-to-Blender connection.

To run Blender without a window, after enabling the add-on:

blender --background --python blender_addon/headless.py

The included systemd/blender-animation-mcp.service runs this worker persistently on port 9877.