blender-mcp-skills

这段内容是审核时保存的快照。外部来源才是完整且最新的版本。

---
name: blender-mcp-skills
description: Use when users need Blender MCP setup or extension workflows, including installing blender-mcp server + Blender MCP add-on components, fixing missing MCP connections, creating extension templates, or handling register/unregister/reload behavior across different runtime systems.
type: skills
---

# Blender MCP — Plugin and Extension Development

This skill provides a reliable workflow for Blender extension add-on development through Blender MCP.

## When to trigger this skill

Trigger this skill whenever users ask to:

- install Blender MCP components (Blender Add-on + blender-mcp server)
- fix missing blender-mcp command or missing agent-side MCP connection
- create plugin scaffolding
- create a template
- create a new add-on
- create a new extension add-on
- migrate legacy add-on structure to extension structure
- debug register/unregister/reload lifecycle issues
- manage private Python dependencies for Blender extensions

## Blender MCP gate (minimal)

Before extension development, run checks in this exact order:

1. `blender-mcp --help` must run successfully.
2. Run one Blender MCP query and fetch these fields together:

   - Blender version (`bpy.app.version_string` or `bpy.app.version`)
   - Blender executable path (`bpy.app.binary_path`)
   - Runtime system (`platform.system()`)

If version is lower than 4.2, stop and explain that the default template targets the Blender Extension system for 4.2+ workflows.

If version is 4.2 or newer, continue. Prefer testing on the user's active Blender version rather than forcing a fixed 5.1+ baseline.

No other gate checks are required.

Setup guide source note:

- This guide is maintained by this repository (not official Blender documentation).
- Its goal is to install official Blender MCP components correctly.

Setup guide (raw URL):

- Local setup (EN): `https://raw.githubusercontent.com/psiQAQ/blender_mcp-setup-guide/main/docs/blender_mcp-setup_en.md`

After installation, re-run the two checks above. Only continue add-on development after both pass.

## First questions to ask

Before implementation, ask:

1. What is the minimum Blender version target?
   - Default recommendation: 4.2+
2. Is extension-only delivery acceptable?
   - Default: yes, extension-only

## Extension install rule (critical)

For extension-only delivery, do not deploy source folders to legacy add-on paths.

Use extension-native flow only:

1. Build zip from extension root.
   - Default output location: parent directory of the extension source folder.
2. Install zip into extension repo (prefer `user_default`).
3. Verify enabled key format `bl_ext.<repo_module>.<extension_id>`.
4. Ensure zip path is readable by Blender host system (especially cross-system cases).

Detailed install steps and examples:

- `references/extension-install.md`
- `references/system-adaptation.md`

## Built-in template policy

- Keep one local template:
  - `templates/extension_addon/`
- Registration strategy is autoload-only (`auto_load.py` topology registration).
- Keep template source code in template directories.
- Do not inline full template source code inside `SKILL.md`.

## Python dependency policy (mandatory)

Read `references/dependency-policy.md` before adding third-party Python packages to an extension.

- Do not run `pip install` without `--target`.
- Do not install into Blender bundled Python global `site-packages`.
- Do not import optional third-party packages at module top level.
- Do not install dependencies silently during import, `register()`, or add-on enable flow.
- Default to showing dependency status in `AddonPreferences` and installing only after a user clicks a button.
- The Tsinghua PyPI mirror may be the default, but users must be able to disable it.
- Recommend an external Python environment for heavy dependencies such as `torch`, `opencv-python`, `scipy`, `open3d`, and CUDA packages.

## System operation rule (mandatory)

Before running Blender commands or touching a