blender-api-cheat

Provide concise Blender Python API guidance for AI agents.

6|Updated Jun 8, 2026
One-click install
npx skills add https://github.com/PoBruno/mcp-blender-agent --skill blender-api-cheat
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: blender-api-cheat
Source: https://github.com/PoBruno/mcp-blender-agent/tree/main/.claude/skills/blender-api-cheat
Command: npx skills add https://github.com/PoBruno/mcp-blender-agent --skill blender-api-cheat

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Provides a concise reference that clarifies Blender's Python API usage and best practices for AI agents building or controlling Blender workflows.

Core Features & Use Cases

  • Quick reference of bpy.data vs bpy.ops, including when to use each for safe, predictable results.
  • Guidance on main-thread restrictions, context overrides, and mode handling to avoid common pitfalls.
  • Real-world examples showing how to select appropriate APIs for modeling, animation, and data extraction tasks.

Quick Start

Review this cheat sheet before implementing a Blender Python tool to ensure correct API usage.

Frequently Asked Questions about blender-api-cheat

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
What is the difference between bpy.data and bpy.ops in the Blender Python API?

bpy.data accesses and modifies raw Blender data directly for safe, predictable results, while bpy.ops executes operator actions that depend heavily on UI context and mode states. Use bpy.data for reliable automation and bpy.ops for interactive tool replication.

How do I avoid context override errors when calling bpy.ops in Blender Python?

To avoid context override errors with bpy.ops, ensure your script runs on the main thread and manually manage context by setting the correct area, region, and active object before execution. Proper context management prevents common pitfalls during operator calls.

Why does my Blender Python script fail with a main-thread restriction error?

Blender Python scripts fail with main-thread restriction errors because bpy.ops operators require execution on the main thread to safely access the user interface context. Calling these operators from background threads without proper context overrides triggers runtime failures.

Can I use Blender Python API for automated modeling and data extraction without opening the GUI?

Yes, you can use the Blender Python API for automated modeling and data extraction by relying on bpy.data to manipulate meshes and properties directly. Accessing data this way bypasses GUI dependencies, whereas bpy.ops often requires a valid UI context.

When should I not use bpy.ops in my Blender Python automation scripts?

You should not use bpy.ops when you need predictable, headless data access or when running outside the main thread. Instead, use bpy.data to directly read or modify mesh, object, and scene properties to avoid context dependencies and mode-switching pitfalls.

What is the best way to switch modes in Blender using the Python API?

The best way to switch modes in Blender using the Python API is to ensure the target object is active and then call the mode switch operator with proper context overrides. Managing context correctly ensures smooth transitions between object, edit, and other modes.