# Blender MCP Server

MCP server for **Cursor** that controls **Blender** through a local HTTP bridge.  
`bpy` runs **inside Blender** — this repo does not import bpy in the MCP process.

**Separate from [Summit](../summit)** — export `.glb` files to Summit's `Assets/` when ready.

## Architecture

```
Cursor Agent → MCP (this repo) → HTTP bridge → bpy → Blender
```

| Path | Role |
|------|------|
| `server.py` | MCP entry (stdio) |
| `mcp_server/` | Tools exposed to the agent |
| `blender_addon/blender_mcp_bridge/` | Blender addon (HTTP + bpy commands) |
| `config.json` | Bridge port, Summit export paths, default `.blend` |

Blender 5.1: `/home/juan/blender-5.1.2/blender`

## Quick start

### 1. Install MCP server (Python)

```bash
cd /home/juan/source/blender_mcp_server
./scripts/setup_mcp.sh
cp config.example.json config.json   # edit paths if needed
```

### 2. Install Blender addon

```bash
BLENDER_VERSION=5.1 ./scripts/install_addon.sh
# Detect version: ls ~/.config/blender/
```

In Blender:

1. **Edit → Preferences → Add-ons** → enable **Blender MCP Bridge**
2. **N panel → MCP tab → Start Server** (default `http://127.0.0.1:9876`)

Or start headless with the default export blend:

```bash
./scripts/start_bridge.sh
```

Logs: `bridge.log` in this repo. Override blend: `BLENDER_MCP_BLEND=/path/to/file.blend ./scripts/start_bridge.sh`

### 3. Connect Cursor

Merge `cursor.mcp.example.json` into `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "blender": {
      "command": "/home/juan/source/blender_mcp_server/.venv/bin/python",
      "args": ["/home/juan/source/blender_mcp_server/server.py"],
      "env": {
        "BLENDER_MCP_CONFIG": "/home/juan/source/blender_mcp_server/config.json"
      }
    }
  }
}
```

Restart Cursor. Open this folder as workspace when animating.

### 4. Test

With Blender bridge running:

```bash
curl -s http://127.0.0.1:9876/health
```

In Cursor chat (with MCP enabled):

> Use ping_blender, then scene_information

## MCP tools

**Connection:** `ping_blender`, `get_server_config`

**Inspection:** `scene_information`, `list_objects`, `list_armatures`, `list_bones`, `list_actions`, `get_object_transform`

**Animation:** `create_action`, `rename_action`, `set_active_action`, `set_frame`, `set_bone_rotation_keyframe`, `set_action_loop_mode`

**Export / validate:** `export_gltf`, `export_to_summit`, `validate_scene_scale`, `validate_action_root_motion`, `validate_rts_asset`, `render_preview`

**Modeling (recipes):** `create_summit_bobcat` — low-poly harvester blockout + `idle` / `harvest` animations

### Bridge-only commands (not MCP tools yet)

Callable via `scripts/run_command.py` or HTTP bridge dispatch:

| Command | Purpose |
|---------|---------|
| `create_natural_idle_action` | Breathing idle from a pose frame (quaternion offsets) |
| `create_rifle_attack_action` | Forward rifle aim + recoil clip |
| `create_idle_action` | Static hold from source action |
| `prepare_rifleman_locomotion` | Import walk GLB, remap bones, strip hip motion, create idle |
| `duplicate_action` | Copy an action |
| `strip_action_root_motion` | Remove root bone location keys |

## Human Rifleman pipeline (current)

Source blends live under `~/Documents/BlenderSaves/summit/`:

| File | Content |
|------|---------|
| `riflemenStand.blend` | `idle` — natural breathing (~48 frames) |
| `riflemenwalk.blend` | `walk` — in-place **rifle run** sprint (22 frames) |
| `riflemenfire.blend` | `attack` — rifle aim + recoil (~24 frames) |
| `riflemenExport.blend` | Merged master (idle + walk + attack) |
| `riflemen-backup-dont-edit.blend` | Safety backup |

**Regenerate walk + attack from stand** (run FBX + procedural fire), then merge + export:

```bash
/home/juan/blender-5.1.2/blender --background --python scripts/prepare_rifleman_animations.py
```

**Body textures (Ch36):** merge exports from `riflemenStand.blend` (painted mesh). The exporter rebuilds `Ch36_Body` for glTF PBR and syncs packed images into the GLB. If sidecar PNGs look stale in Godot, reimport `Rifleman.glb` or run:

```bash
/home/juan/blender-5.1.2/blender --background --python scripts/fix_and_export_rifleman_body.py
/home/juan/blender-5.1.2/blender --background --python scripts/extract_textures_from_glb.py
```

**Re-export only** (if walk/fire blends already exist):

```bash
/home/juan/blender-5.1.2/blender --background --python scripts/prepare_rifleman_export.py
```

Output: `/home/juan/source/summit/Assets/Units/Human/Rifleman.glb`  
Godot view: `Scenes/Units/HumanRiflemanView.tscn` (animations `idle`, `walk`, `attack`).

Rifle mesh is parented to `mixamorig1:RightHand` in the fire blend. Attack uses explicit aim quaternions (+Y barrel forward), not a copied walk pose.

Or export from the open blend via MCP:

```
export_to_summit(target_key="summit_human_units", filename="Rifleman.glb", action_names=["idle","walk","attack"])
```

## Bobcat harvester (vehicle recipe)

### V2 (RTS parts catalog — recommended)

Procedural **Generals-style** assembly from reusable mechanical parts:

```bash
BLENDER_VERSION=5.1 ./scripts/install_addon.sh
/home/juan/blender-5.1.2/blender --background --python scripts/create_summit_bobcat_v2.py
```

Output blend: `~/Documents/BlenderSaves/summit/bobcatExport.blend`  
Silhouette preview: `~/Documents/BlenderSaves/summit/bobcat_v2_silhouette.png`  
Output GLB: `/home/juan/source/summit/Assets/Units/Human/Bobcat.glb` (`idle`, `harvest`)

MCP: `create_summit_bobcat_v2`, `validate_rts_asset`, `validate_rts_silhouette`, `render_rts_silhouette_preview`

Parts catalog (`modeling/parts/`): cabin, wheel, bucket, hydraulic, chassis, fender, exhaust, headlight, arm, grille.

Animated pivots (stable Godot contract): `Bobcat_Arm_L`, `Bobcat_Arm_R`, `Bobcat_Bucket`.

### V1 (blockout)

```bash
/home/juan/blender-5.1.2/blender --background --python scripts/create_summit_bobcat.py
```

## Summit export

Config keys in `config.json`:

```json
"export_targets": {
  "summit_human_units": "/home/juan/source/summit/Assets/Units/Human",
  "summit_props": "/home/juan/source/summit/Assets/Props"
}
```

Default blend: `riflemenExport.blend` (see `default_blend` in config).

Then switch workspace to `/home/juan/source/summit` to wire Godot views and sim.

## Summit conventions

| Rule | Value |
|------|--------|
| Scale | 1 Blender unit = 1 meter |
| Infantry height | ~**1.6 m** (`Ch36` reference mesh) |
| Forward | **+Y** in Blender |
| Animation names | `idle`, `walk`, `attack`, `death` (infantry); vehicles: `idle`, `harvest` |
| Vehicle tri budget | **2500** tris (blockout recipe) |
| Locomotion | Walk **in place** — no hip translation (`validate_action_root_motion`) |

See also Summit [player identity](../summit/docs/02-Architecture/player-identity.md) for **team color masks** when authoring units:

- Paint tint regions in Blender (vertex color or `*_TeamMask.png`)
- One GLB per unit type; player color applied at runtime in Godot
- Human = military paint zones; Robot = LED emissive mask; etc.

## Headless

```bash
blender mychar.blend --background --python scripts/run_command.py -- '{"command":"scene_information","args":{}}'
```

## Roadmap

- [x] Rifleman idle / walk / attack pipeline + `prepare_rifleman_export.py`
- [x] Bobcat blockout recipe + `create_summit_bobcat.py`
- [x] `validate_rts_asset` + MCP modeling tools
- [x] `create_natural_idle_action`, `create_rifle_attack_action` (bridge)
- [x] `start_bridge.sh` headless bridge daemon
- [ ] Expose locomotion commands as MCP tools
- [ ] Team color mask validation / export hints for Summit shader
- [ ] `death` animation for rifleman
- [ ] Rigging helpers
- [ ] Auto tool registration review gate