Kết nối Blender với LLM qua MCP for Blender

Bài này hướng dẫn cài và dùng MCP for Blender để AI hỗ trợ dựng mô hình 3D, tạo và chỉnh sửa cảnh trong Blender bằng prompt.

MCP for Blender kết nối Blender với bất kỳ LLM nào qua Model Context Protocol (MCP). Dự án trước đây tên là blender-mcp, package PyPI nay là mcp-for-blender. Các thiết lập cũ vẫn chạy, không cần đổi cấu hình (đọc thêm).

Bắt đầu nhanh

Một lệnh thiết lập các ứng dụng AI của bạn và addon Blender:

macOS / Linux

curl -LsSf https://www.mcp-for-blender.com/install.sh | sh

Windows (PowerShell)

powershell -ExecutionPolicy ByPass -c "irm https://www.mcp-for-blender.com/install.ps1 | iex"

Đã có uv? Chạy uvx mcp-for-blender setup thay thế.

Lệnh này cài uv nếu cần, tìm các MCP client trên máy bạn (Claude Desktop, Claude Code, Codex, Cursor, VS Code, Devin Desktop/Windsurf, OpenCode, Antigravity) và cho bạn chọn client nào cần thiết lập. Sau đó nó cài addon Blender và bật addon. Cấu hình hiện có được giữ nguyên: lệnh chỉ thêm một mục blender và lưu bản .bak cho mỗi file nó sửa.

Sau đó thoát hẳn rồi mở lại ứng dụng AI (trên Windows, thoát từ khay hệ thống), mở Blender và yêu cầu nó dựng gì đó. Addon tự khởi động server khi Blender mở.

Tính năng

Thành phần

Hệ thống gồm hai thành phần chính:

1. Blender Addon (addon.py): addon tạo một socket server bên trong Blender để nhận và thực thi lệnh.
2. MCP Server (src/blender_mcp/server.py): server Python hiện thực Model Context Protocol và kết nối tới addon Blender.

Cài đặt thủ công

Cách nhanh nhất là trình cài một dòng ở mục Bắt đầu nhanh. Phần dưới đây dành cho thiết lập thủ công.

Yêu cầu

• Blender 3.0 trở lên
• Python 3.10 trở lên
• Trình quản lý package uv

Cài uv theo từng nền tảng:

macOS

brew install uv

Windows

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Sau đó thêm uv vào user path trên Windows (có thể cần khởi động lại Claude Desktop sau bước này):

$localBin = "$env:USERPROFILE\.local\bin"
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$userPath;$localBin", "User")

Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

uv được cài vào ~/.local/bin, hãy mở shell mới để nó có trong PATH. Hướng dẫn cài khác có trên trang Install uv.

Trên mọi hệ điều hành, hãy dùng trình cài chính thức ở trên, không dùng pip install uv. Cách đó có thể không tạo lệnh uvx và có thể giấu uv trong một môi trường mà client của bạn không thấy.

Giúp client tìm thấy uvx

MCP client khởi động từ giao diện đồ hoạ (Claude Desktop, Cursor, VS Code mở từ Dock/Start menu) không kế thừa PATH của terminal. Vì vậy "command": "uvx" trần có thể lỗi spawn uvx ENOENT dù uvx chạy được trong terminal. Khi gặp lỗi này:

• Tìm đường dẫn đầy đủ của uvx bằng which uvx (macOS/Linux) hoặc where uvx (Windows), rồi dùng nó làm "command", ví dụ /opt/homebrew/bin/uvx hoặc C:\Users\<you>\.local\bin\uvx.exe.
• Trên Windows, bạn có thể bọc lại: "command": "cmd", "args": ["/c", "uvx", "mcp-for-blender"].
• Sau mọi thay đổi PATH hoặc cấu hình, thoát hẳn rồi mở lại client (Windows: thoát từ khay hệ thống, không chỉ đóng cửa sổ; macOS: Cmd+Q).

Cố định phiên bản Python

uv chọn Python nào chạy server. Trên máy có conda (tự kích hoạt base), pyenv hoặc asdf, hoặc có bản CPython mới mà một số dependency chưa có wheel, uv có thể lấy một interpreter làm cài đặt thất bại. Hãy cố định Python 3.11 và ưu tiên interpreter do uv quản lý để tránh dùng bất kỳ thứ gì có trong PATH:

{
    "mcpServers": {
        "blender": {
            "command": "uvx",
            "args": ["--python", "3.11", "mcp-for-blender"],
            "env": { "UV_PYTHON_PREFERENCE": "only-managed" }
        }
    }
}

--python 3.11 vẫn thoả requires-python >=3.10 của package, còn UV_PYTHON_PREFERENCE=only-managed ngăn uv chọn conda, pyenv, asdf hoặc Python hệ thống trước. Nếu một lần thử lỗi trước đó cứ lặp lại sau khi đã sửa, hãy xoá cache:

uv cache clean mcp-for-blender blender-mcp && uvx --refresh mcp-for-blender

Biến môi trường

Các biến môi trường sau dùng để cấu hình kết nối Blender:

Bạn cũng có thể truyền thông tin kết nối bằng cờ CLI, cờ CLI được ưu tiên hơn biến môi trường. Cách này tiện khi chạy nhiều instance Blender song song, vì mỗi mục MCP client trỏ tới một cổng khác nhau:

uvx mcp-for-blender --port 9877

Trong cấu hình MCP client, đó là một mục thứ hai chỉ khác ở args:

{
  "mcpServers": {
    "blender": { "command": "uvx", "args": ["mcp-for-blender"] },
    "blender-b": { "command": "uvx", "args": ["mcp-for-blender", "--port", "9877"] }
  }
}

Mỗi instance cần đặt cổng tương ứng trong panel addon của Blender.

Safe mode

Mặc định, AI có thể chạy bất kỳ code Python nào trong Blender. Đặt BLENDER_MCP_SAFE_MODE=1 để kiểm tra mọi script trước khi chạy và chặn code rủi ro, như đọc ghi file trực tiếp, chạy chương trình khác, truy cập mạng, hoặc cài code tiếp tục chạy sau khi script kết thúc. Công việc Blender bình thường (dựng mô hình, vật liệu, render, lưu, import/export) vẫn chạy. Script bị chặn được gửi lại cho AI kèm lý do, để AI thử lại với bản đã sửa.

Thiết lập MCP client

Claude for Desktop

Xem video hướng dẫn thiết lập (giả định bạn đã cài uv).

Vào Claude → Settings → Developer → Edit Config → claude_desktop_config.json và thêm:

{
    "mcpServers": {
        "blender": {
            "command": "uvx",
            "args": [
                "mcp-for-blender"
            ]
        }
    }
}

Claude Code

Dùng Claude Code CLI để thêm server MCP for Blender:

claude mcp add blender uvx mcp-for-blender

Codex

Codex CLI, ứng dụng desktop và extension IDE dùng chung một file cấu hình (~/.codex/config.toml), nên thiết lập server một lần là dùng được cho cả ba. Đăng ký server bằng Codex CLI:

codex mcp add blender -- uvx mcp-for-blender

Hoặc thêm tay vào ~/.codex/config.toml (hoặc $CODEX_HOME/config.toml):

[mcp_servers.blender]
command = "uvx"
args = ["mcp-for-blender"]

Kiểm tra đã đăng ký bằng codex mcp list, server blender phải hiện enabled. Các tool sẽ có từ lần khởi động Codex tiếp theo.

Cursor

macOS: vào Settings → MCP và dán đoạn sau:

• Dùng làm server global: bấm nút "add new global MCP server" rồi dán
• Dùng làm server riêng cho dự án: tạo .cursor/mcp.json ở thư mục gốc dự án rồi dán

{
    "mcpServers": {
        "blender": {
            "command": "uvx",
            "args": [
                "mcp-for-blender"
            ]
        }
    }
}

Windows: vào Settings → MCP → Add Server, thêm server mới với thiết lập:

{
    "mcpServers": {
        "blender": {
            "command": "cmd",
            "args": [
                "/c",
                "uvx",
                "mcp-for-blender"
            ]
        }
    }
}

Video thiết lập Cursor

Visual Studio Code

Đảm bảo bạn đã cài Visual Studio Code, rồi dùng link cài server mcp-for-blender cho VS Code.

OpenCode

{
  "mcp": {
    "blender-mcp": {
      "type": "local",
      "command": ["uvx", "mcp-for-blender"],
      "enabled": true,
      "environment": {
        "BLENDER_HOST": "localhost",
        "BLENDER_PORT": "9876"
      }
    }
  }
}

Antigravity

{
  "mcpServers": {
    "blender-mcp": {
      "command": "uvx",
      "args": ["mcp-for-blender"],
      "env": {
        "BLENDER_HOST": "localhost",
        "BLENDER_PORT": "9876"
      }
    }
  }
}

Cài addon Blender

uvx mcp-for-blender setup làm toàn bộ việc này, kể cả bật addon. Các bước dưới là cách làm tay.

1. Khuyên dùng: chạy trong terminal:

   bash

   Sao chép mã

   uvx mcp-for-blender install-addon
   

   Lệnh này chép addon vào thư mục addon của Blender với tên blender_mcp.py, in ra nơi đã ghi và giữ bản .bak của file bị thay. Tuỳ chọn: uvx mcp-for-blender addon-paths liệt kê các thư mục addon Blender tìm thấy, đổi đích bằng BLENDERMCP_ADDONS_DIR=/path/to/scripts/addons.

2. Mở Blender.

3. Vào Edit → Preferences → Add-ons.

4. Bật Interface: MCP for Blender (tìm "MCP for Blender"). Nếu chưa thấy, bấm Install… và chọn file blender_mcp.py / addon.py đã chép, hoặc khởi động lại Blender.

5. Cách thủ công khác: nếu lệnh trên không tìm thấy bản cài Blender, hoặc bạn muốn tự làm, tải addon.py từ repo, trong Blender vào Edit → Preferences → Add-ons → Install…, chọn file addon.py đã tải rồi bật nó.

Sau đó mở tab MCP for Blender ở thanh bên của Blender (nhấn N trong 3D viewport) và bấm Start MCP Server.

Sử dụng

Bắt đầu kết nối

1. Trong Blender, mở thanh bên 3D View (nhấn N nếu chưa hiện).
2. Tìm tab MCP for Blender.
3. Bật các ô bạn muốn dùng (xem thêm ở mục Khả năng bên dưới).
4. Bấm Connect to Claude.
5. Đảm bảo MCP server đang chạy trong terminal.

Dùng với Claude

Khi đã đặt file cấu hình cho Claude và addon đang chạy trong Blender, bạn sẽ thấy biểu tượng búa kèm các tool của MCP for Blender.

Khả năng

AI tự viết Blender Python cho dựng mô hình, bố cục, vật liệu, animation, rigging và retopology. MCP bổ sung những gì Python không tự làm được, dưới dạng mười tool:

Giấy phép và ghi công asset

• Poly Haven: mọi asset đều là CC0. Bạn không bao giờ phải ghi công ai, cho bất kỳ mục đích nào, thương mại hay không. Điều khoản API của họ yêu cầu phần mềm dùng API trực tiếp phải nói rõ asset đến từ đâu, nên kết quả tìm kiếm và import đều ghi nguồn và link tới trang của asset. Khi import, polyhaven_id, polyhaven_url, polyhaven_authors, polyhaven_resolution và polyhaven_licence được ghi vào đối tượng, material, ảnh và world đã import dưới dạng custom property.
• Poly Pizza: khoảng 69% danh mục là CC-BY, giấy phép này bắt buộc bạn ghi công tác giả ở mọi nơi model xuất hiện. Khi import, dòng ghi công định dạng sẵn được ghi vào từng đối tượng gốc dưới dạng custom property polypizza_attribution (cùng polypizza_id và polypizza_licence), nên nó được lưu trong file .blend và còn lại sau phiên làm việc. Lọc bằng licence="CC0" nếu bạn muốn dùng model không cần ghi công.

Lệnh mẫu

Một số ví dụ bạn có thể yêu cầu Claude làm:

Lưu API credential lâu dài

MCP for Blender hỗ trợ lưu credential lâu dài qua Add-on Preferences của Blender, tại Edit → Preferences → Add-ons → MCP for Blender. Bạn có thể lưu các giá trị sau để chúng còn sau khi khởi động lại Blender:

• Sketchfab API Key
• Poly Pizza API Key
• Hyper3D API Key
• Hunyuan3D SecretId / SecretKey
• Hunyuan3D API URL

Với thiết lập headless hoặc CI, credential cũng có thể được truyền qua biến môi trường: BLENDERMCP_SKETCHFAB_API_KEY, BLENDERMCP_POLYPIZZA_API_KEY, BLENDERMCP_HYPER3D_API_KEY, BLENDERMCP_HUNYUAN3D_SECRET_ID, BLENDERMCP_HUNYUAN3D_SECRET_KEY, BLENDERMCP_HUNYUAN3D_API_URL.

Khắc phục sự cố

Giới hạn và lưu ý bảo mật

• Poly Haven cần tải model, texture và ảnh HDRI. Nếu không muốn dùng, hãy tắt nó ở ô chọn trong Blender.
• Các thao tác phức tạp có thể cần chia thành các bước nhỏ hơn.

Điều khiển telemetry

Telemetry là opt-in. Việc thu thập nội dung của bạn mặc định tắt và giữ tắt tới khi bạn chủ động bật.

Thu thập mặc định (không cần opt-in): một bản ghi sử dụng ẩn danh tối thiểu để tác giả đếm số người dùng hoạt động và xem tool nào được dùng. Bản ghi gồm ID cài đặt sinh ngẫu nhiên, ID phiên, tên tool, có thành công hay không, mất bao lâu, phiên bản MCP for Blender và Blender, hệ điều hành của bạn và một mốc thời gian.

Không bao giờ thu thập khi chưa opt-in: prompt của bạn, code được sinh, ảnh chụp viewport, dữ liệu cảnh và các bước trajectory.

Để opt-in: vào Edit → Preferences → Add-ons → MCP for Blender và tích ô đồng ý telemetry. Một số MCP client cũng sẽ hỏi opt-in một lần khi bắt đầu hội thoại. Opt-in sẽ thêm prompt, code được sinh, ảnh chụp màn hình và dữ liệu trajectory vào phần được thu thập; xem TnC để biết chi tiết. Bạn có thể tắt lại ở cùng chỗ bất cứ lúc nào.

Để tắt hoàn toàn telemetry, kể cả bản ghi sử dụng ẩn danh tối thiểu, đặt biến môi trường:

DISABLE_TELEMETRY=true uvx mcp-for-blender

Hoặc thêm vào cấu hình MCP:

{
    "mcpServers": {
        "blender": {
            "command": "uvx",
            "args": ["mcp-for-blender"],
            "env": {
                "DISABLE_TELEMETRY": "true"
            }
        }
    }
}

Dữ liệu telemetry không gắn với tên hay tài khoản của bạn. Dữ liệu có thể được dùng để cải thiện MCP for Blender, cho nghiên cứu, và để huấn luyện model AI.

Chi tiết đầy đủ về dữ liệu được thu thập và giấy phép bạn cấp khi opt-in có trong TERMS_AND_CONDITIONS.md.

Nguồn

• Dịch và biên tập từ https://raw.githubusercontent.com/ahujasid/mcp-for-blender/main/README.md, giấy phép MIT.