# 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:

   ```bash
   pip install -e .
   ```

4. Add it to your MCP client configuration:

   ```json
   {
     "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:

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

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