VN MCP Blender

MCP server giúp AI dựng mô hình nhà 3D trong Blender từ dữ liệu kiến trúc, đọc được mặt bằng DXF từ AutoCAD và bóc khối lượng từ chính mô hình.

Viết riêng cho hồ sơ nhà ở Việt Nam: tường 220 và 110, cột bê tông, dầm, sàn, cầu thang, mái bằng. Mọi số đo tính bằng mét.

Làm được gì

Tổng cộng 30 công cụ. Danh sách đầy đủ ở docs/cong-cu.md.

Cài đặt

Cần hai thứ: MCP server và addon trong Blender. Xem hướng dẫn từng bước ở docs/cai-dat.md, hoặc làm nhanh như dưới.

Yêu cầu

• Blender 3.0 trở lên
• Python 3.10 trở lên
• Claude Code, Claude Desktop, hoặc bất kỳ ứng dụng nào nối được MCP

Bước 1: cài gói

git clone https://github.com/andyluu98/vn-mcp-blender
cd vn-mcp-blender
pip install -e .

Bước 2: cài addon vào Blender

vn-mcp-blender install-addon

Lệnh này tự tìm Blender trên máy và chép addon vào. Sau đó trong Blender:

1. Edit > Preferences > Add-ons
2. Tìm MCP Xây Dựng, tích vào ô bên trái để bật
3. Trong khung nhìn 3D, bấm phím N để mở thanh bên
4. Chọn tab MCP Xây Dựng, bấm Bật kết nối

Bước 3: khai báo với Claude

Thêm vào file cấu hình MCP:

{
  "mcpServers": {
    "vn-blender": {
      "command": "vn-mcp-blender"
    }
  }
}

File cấu hình nằm ở:

Khởi động lại Claude, rồi thử bảo: “kiểm tra kết nối Blender”.

Kiểm tra nhanh không cần Claude

vn-mcp-blender check

Dùng thử

Mở Blender, bật addon, rồi bảo Claude:

Dựng cho tôi nhà phố 5m x 14m, 1 tầng, tường bao 220 cao 3.1m, sàn dày 100, 4 cột 220x220 ở bốn góc. Xong thì cho tôi xem ảnh.

Hoặc dựng từ bản vẽ có sẵn:

Đọc file F:/ban-ve/mat-bang.dxf xem có layer gì, rồi dựng tường lên 3D.

Trong thư mục examples/ có sẵn mô tả một căn nhà phố 5x20m, 3 tầng 1 tum lấy từ hồ sơ thật. Dựng thử bằng:

blender --background --python scripts/dung-vi-du.py

Kiến trúc

Blender không nói chuyện MCP trực tiếp được, nên bộ này chia hai nửa:

Claude    MCP server    Addon trong Blender

MCP server khai báo công cụ và đọc file DXF. Addon làm mọi việc dựng hình bằng thư viện bpy. Chi tiết ở docs/kien-truc.md.

Cổng mặc định là 9877, chọn khác 9876 để không đâm vào addon blender-mcp phổ biến nếu bạn đang dùng cả hai.

Phát triển

pip install -e ".[dev]"
pytest

50 test chạy được mà không cần mở Blender. Riêng phần hình học có script tự kiểm tra chạy trong Blender thật:

blender --background --python scripts/tu-kiem-tra.py

Cách thêm công cụ mới: docs/phat-trien.md.

An toàn

Công cụ chay_python cho phép chạy Python bất kỳ trong Blender. Code được soát trước để chặn xóa file, chạy lệnh hệ thống, và các thao tác làm mất bản vẽ đang mở. Xem src/vn_mcp_blender/safe_mode.py.

Bộ soát này chặn lỗi rõ ràng, không phải tường lửa. Vẫn nên đọc code trước khi cho chạy trên bản vẽ quan trọng, và lưu file trước khi làm việc lớn.

Bộ công cụ này không gửi dữ liệu đi đâu. Không có telemetry.

Ghi chú về ngôn ngữ

Tài liệu và chữ hiện trên giao diện viết tiếng Việt có dấu. Riêng chú thích trong mã nguồn viết không dấu, để chạy được trên mọi máy không phụ thuộc bảng mã, kể cả khi Blender dùng bản Python cũ hoặc hệ điều hành đặt locale lạ.

Giấy phép

MIT. Xem LICENSE.

Dự án độc lập, không liên quan đến Blender Foundation.