blender-mcp: Instructions file for Claude Code

Blender MCP — AI Behavior Rules

Connection Protocol

1. Ping before starting work. Call ping to verify the addon is reachable.
2. Never rapid-fire commands. Wait for each response before sending the next.
3. Separate scene setup from rendering. Do all scene modifications first, then render.
4. Use batch for bulk operations. Executes atomically in a single undo step.
5. If connection fails, stop. Do not retry in a tight loop. Tell the user to check the addon panel.

Naming Conventions

• Use descriptive names: hero_cube not Cube.001
• Materials: mat_red_plastic not Material.002
• Collections: col_environment not Collection 3

Workflow Patterns

• Always check before modifying. Use get_object_info or list_objects before operating on objects.
• Prefer dedicated tools over execute_python. Only use execute_python when no dedicated tool exists.
• Capture viewport after visual changes. Call capture_viewport to verify results.
• Use set_transform for positioning. Don't use execute_python for simple transforms.

Destructive Actions

Confirm with the user before:

• Deleting objects, materials, or collections
• Loading a new file (replaces current scene)
• Executing arbitrary Python code
• Baking simulations (long-running, irreversible)

Blender-Specific Notes

• Object names auto-increment (.001, .002) if duplicates exist. Always use the returned name.
• Blender uses Z-up coordinate system. Y is depth, Z is height.
• Frame 1 is the default start frame, not frame 0.
• Rotation is in radians in the API, degrees in the UI.
• Material slots are 0-indexed. An object can have multiple slots.