Blender AI控制工具

Claude / AI Agent
       │  stdio  (JSON-RPC 2.0 / MCP)
       ▼
stdio_bridge.py              ← MCP bridge  [standard Python, runs outside Blender]
       │                       · Validates JSON schemas before forwarding
       │                       · Caches tool list from Blender on first connect
       │  TCP localhost:9879  (4-byte Big-Endian length-prefix + JSON body)
       ▼
Blender Addon                ← blender_mcp/__init__.py  [runs inside Blender]
  ├── dispatcher.py            Command router + handler registry (HANDLER_REGISTRY)
  ├── handlers/                52 handler modules (manage_*.py)
  │     manage_scene_comprehension.py   11-action scene intelligence suite
  │     manage_rendering.py             Render, screenshot, view control
  │     manage_scripting.py             execute_blender_code (safe eval)
  │     polyhaven / sketchfab / hunyuan / hyper3d  (4 external integrations)
  └── core/
        protocol.py           Wire protocol (4-byte header + JSON)
        thread_safety.py      All bpy calls routed to Blender's main thread
        execution_engine.py   Safe bpy.ops wrapper + ExecutionPolicy
        parameter_validator.py Type coercion + JSON schema validation
        intent_router.py      Multi-language intent classification (EN/TR/FR)
        semantic_memory.py    Tag-based object resolution
        security.py           High Mode / Safe Mode toggle
        job_manager.py        Async subprocess + internal job queue

# Create .venv and install all dependencies in one command
uv sync --all-extras

# Verify everything works (no Blender needed for tests)
uv run pytest tests/unit -q
# → 499 passed in ~1.4s

python -m venv .venv
# Windows:
.venv\Scripts\activate
# macOS / Linux:
source .venv/bin/activate

pip install -e ".[dev]"

{
  "mcpServers": {
    "blender": {
      "command": "python",
      "args": ["-u", "<path-to-blender-mcp>/stdio_bridge.py"],
      "env": {
        "BLENDER_HOST": "localhost",
        "BLENDER_PORT": "9879",
        "MCP_TRANSPORT": "stdio",
        "PYTHONPATH": "<path-to-blender-mcp>"
      }
    }
  }
}

{
  "mcpServers": {
    "blender": {
      "command": "python",
      "args": ["-u", "<path-to-blender-mcp>/stdio_bridge.py"],
      "env": {
        "BLENDER_HOST": "localhost",
        "BLENDER_PORT": "9879",
        "MCP_TRANSPORT": "stdio",
        "PYTHONPATH": "<path-to-blender-mcp>"
      }
    }
  }
}

[mcp_servers.blender]
command = "python"
args = ["-u", "<path-to-blender-mcp>/stdio_bridge.py"]
cwd = "<path-to-blender-mcp>"
enabled = true

[mcp_servers.blender.env]
BLENDER_HOST = "localhost"
BLENDER_PORT = "9879"
MCP_TRANSPORT = "stdio"
PYTHONPATH = "<path-to-blender-mcp>"

export BLENDER_HOST=localhost
export BLENDER_PORT=9879
export MCP_TRANSPORT=stdio
export PYTHONPATH=<path-to-blender-mcp>

python -u <path-to-blender-mcp>/stdio_bridge.py

uv sync --all-extras          # Install all dependencies

make check           # 12 checks: lint + format + type-check + tests
make check-fast      # 8 checks: lint + custom checks
make test-fast       # Unit tests only, stop on first failure

make inspect-summary        # Compact table of all 69 tools
make inspect-essential      # ESSENTIAL tier full detail
uv run python scripts/inspect_tools.py --tool get_scene_graph
uv run python scripts/inspect_tools.py --cat animation

from ..dispatcher import register_handler

@register_handler(
    "manage_my_feature",
    actions=["CREATE", "DELETE", "LIST"],
    schema={
        "type": "object",
        "properties": {
            "action": {"type": "string", "enum": ["CREATE", "DELETE", "LIST"]},
            "name":   {"type": "string"},
        },
        "required": ["action"],
    },
    category="scene",
    priority=60,          # 1-9=ESSENTIAL, 10-49=CORE, 50-149=STANDARD, 150+=OPTIONAL
    description="STANDARD — Create, delete, and list my features.",
)
def manage_my_feature(action, **params):
    if action == "CREATE":
        return {"created": params.get("name")}
    elif action == "LIST":
        return {"items": []}

python -m blender_mcp --help        # Quick CLI overview
python -m blender_mcp --list-tools  # List all tools
python -m blender_mcp --status      # Project health

Blender_mcp/
├── blender_mcp/                     Blender addon (installs via ZIP)
│   ├── __init__.py                  Addon entry + BlenderMCPServer + N-panel UI
│   ├── __main__.py                  python -m blender_mcp CLI
│   ├── dispatcher.py                Handler registry + dispatch_command
│   ├── __version__.py               Single source of version truth
│   ├── handlers/                    52 handler modules
│   │   ├── manage_scene_comprehension.py   get_scene_graph (11 actions)
│   │   ├── manage_rendering.py             RENDER_FRAME, screenshot
│   │   ├── manage_scripting.py             execute_blender_code
│   │   ├── manage_agent_context.py         GET_PRIMER, GET_TACTICS
│   │   ├── manage_history.py               Session checkpoints
│   │   ├── get_local_transforms.py         Parent-relative coordinates
│   │   ├── polyhaven_handler.py            Polyhaven CC0 assets
│   │   ├── sketchfab_handler.py            Sketchfab 3D models
│   │   ├── hunyuan_handler.py              Hunyuan3D AI generation
│   │   ├── hyper3d_handler.py              Hyper3D Rodin AI generation
│   │   └── ...                             40+ more handlers
│   └── core/
│       ├── protocol.py              Wire protocol (4-byte header + JSON)
│       ├── thread_safety.py         Main-thread routing via bpy.app.timers
│       ├── execution_engine.py      Safe bpy.ops + ExecutionPolicy
│       ├── parameter_validator.py   Type coercion + schema validation
│       ├── intent_router.py         Multi-language intent classification
│       ├── semantic_memory.py       Tag-based object resolution
│       ├── security.py              High Mode / Safe Mode
│       ├── job_manager.py           Async subprocess queue
│       ├── response_builder.py      Structured response format
│       └── error_protocol.py        280+ ErrorCode enum values
├── stdio_bridge.py                  MCP bridge (runs outside Blender)
├── scripts/
│   ├── SCRIPTS.md                   Full scripts documentation
│   ├── inspect_tools.py             Tool catalog inspector
│   ├── count_tools.py               Handler count audit
│   ├── sync_version.py              Version synchronization
│   ├── test_blender_imports.py      Runtime import validation (needs Blender)
│   ├── remove_unused_ignores.py     mypy cleanup helper
│   └── quality/
│       ├── run_checks.py            Quality gate (8–12 checks)
│       ├── check_version.py         Version consistency
│       ├── check_forbidden.py       Fatal Blender 5.x pattern scanner
│       ├── check_handler_completeness.py  Registry audit
│       ├── check_handler_imports.py Import style validator
│       ├── check_schemas.py         JSON schema validator
│       ├── check_tool_groups.py     Tool group integrity
│       └── lint_imports.py          Import architecture rules
├── tests/
│   ├── unit/                        499 unit tests (17 files, no Blender needed)
│   ├── integration/                 24 mock + live integration tests
│   └── TESTS.md                     Test suite documentation
├── docs/
│   └── ARCHITECTURE.md              System design, wire protocol, thread model
├── create_release_zip.py            Builds the addon ZIP for Blender
├── Makefile                         Developer shortcuts
├── pyproject.toml                   Build + lint + type-check config
└── LICENSE                          MIT License