vn-revit-mcp

Bộ công cụ tiếng Việt để dùng Claude (hoặc AI khác hỗ trợ MCP) với Autodesk Revit, gồm hai phần:

Hai phần chạy song song: Claude dùng phần A để dựng, rồi dùng phần B để kiểm lại khối lượng vừa dựng.

Trạng thái: bản thử 0.2.0. Hãy thử trên một mô hình nháp trước. Gặp lỗi xin mở Issue.

---

Mục lục

1. Cách hoạt động
2. Yêu cầu
3. Cài đặt
4. Vẽ trên Revit bằng Claude
5. Thống kê và khối lượng
6. An toàn và dữ liệu
7. Xử lý lỗi
8. Gỡ cài đặt
9. Phát triển
10. Liên quan đến pyRevit và nguồn tham khảo

---

1. Cách hoạt động

                     Claude Code / Claude Desktop / Cursor ...
                       │                              │
          MCP "pyrevit" (vẽ)                MCP "vn-revit" (thống kê)
          + skill ve-revit                            │
                       │                              │ gọi lệnh: pyrevit agent run 
                       ▼                              ▼
                 pyRevit CLI ──(đường ống nội bộ Windows, không mở cổng mạng)──►
                 pyRevit agent host trong Revit ──► Revit API ──► mô hình đang mở

Phần A, vẽ: Claude tự viết một đoạn Python dùng Revit API (ví dụ “tạo 4 bức tường 200 quanh lô 5x15 m”) rồi gửi qua công cụ run_modify của pyRevit. pyRevit chạy đoạn code đó bên trong Revit, gom mọi thay đổi vào một nhóm, rồi hiện hộp Keep / Discard ngay trong Revit. Bạn bấm Keep thì thay đổi được lưu thành một mục Undo; bấm Discard thì mô hình trở lại như cũ.

Skill ve-revit là “sổ tay” dạy Claude làm việc này theo cách của người Việt: số liệu mm, cốt ±0.000 tại sàn tầng 1, dựng từng chặng, chạy thử trước khi chạy thật, tra loại tường, cửa có sẵn trong mô hình thay vì đoán tên, không tự bịa kích thước.

Phần B, thống kê: vn-revit-mcp chỉ chạy 9 script viết sẵn trong gói. AI không gửi code tùy ý qua phần này được. 10 trên 11 công cụ chỉ đọc mô hình.

2. Yêu cầu

3. Cài đặt

3.1. Cách nhanh: nhờ Claude cài

Mở Claude Code và dán câu sau:

Cài bộ vn-revit-mcp cho tôi theo README ở https://github.com/andyluu98/vn-revit-mcp, mục 3.2, đủ 8 bước.
Kiểm tra máy đã có pyRevit 7 và uv chưa; thiếu thì hướng dẫn tôi từng bước vì tôi không rành terminal.
Đặt pyRevit ở chế độ ask (mỗi lần sửa mô hình đều hỏi tôi trong Revit). Không dùng chế độ auto.
Làm xong thì nhắc tôi khởi động lại Revit và Claude Code, rồi kiểm tra kết nối.

3.2. Cách tự làm

Các lệnh dưới đây chạy trong PowerShell (bấm Start, gõ PowerShell). Mỗi khi cài thêm chương trình, nên mở cửa sổ PowerShell mới.

Bước 1. Cài pyRevit 7. Tải file .exe ở trang Releases, cài với lựa chọn mặc định. Kiểm tra:

pyrevit --version

Bước 2. Bật agent host và đặt chế độ hỏi trước khi sửa:

pyrevit configs agent enable
pyrevit configs agent policy ask

Bước 3. Đăng ký MCP của pyRevit (phần vẽ) vào Claude Code:

pyrevit mcp install claude

Dùng client khác thì thay claude bằng codex, cursor, vscode hoặc opencode. Với Claude Desktop, thêm vào claude_desktop_config.json:

{
  "mcpServers": {
    "pyrevit": { "command": "pyrevit", "args": ["mcp"] }
  }
}

Bước 4. Đăng ký vn-revit-mcp (phần thống kê):

claude mcp add vn-revit -s user '--' uvx --from git+https://github.com/andyluu98/vn-revit-mcp vn-revit-mcp

Trên PowerShell phải để '--' trong ngoặc đơn. Trên cmd hoặc bash thì viết -- không cần ngoặc. Với Claude Desktop, thêm vào cùng file cấu hình:

"vn-revit": {
  "command": "uvx",
  "args": ["--from", "git+https://github.com/andyluu98/vn-revit-mcp", "vn-revit-mcp"]
}

Bước 5. Cài skill ve-revit cho cả Claude Code và pyRevit, kèm thư mục dữ liệu mặt bằng mẫu:

uvx --from git+https://github.com/andyluu98/vn-revit-mcp vn-revit-mcp cai-skill --workspace D:\DuAn\revit-workspace

Lệnh này chép skill vào:

Đã có bản cũ khác nội dung thì bản cũ được chuyển vào Documents\vn-revit-mcp\_backup, không bị xóa. File đã có trong thư mục workspace thì giữ nguyên.

Bước 6. Cho pyRevit đọc skill của người dùng:

pyrevit configs agent skills enable

Bước 7. Cho Claude Code chờ lâu hơn khi bạn đang xem hộp Keep / Discard. Mặc định Claude Code có thể bỏ cuộc trước khi bạn kịp bấm. Đặt 10 phút:

setx MCP_TOOL_TIMEOUT 600000

Bước 8. Khởi động lại Revit, mở một mô hình, khởi động lại Claude Code. Kiểm tra:

pyrevit agent status
claude mcp list

Thấy phiên Revit trong danh sách đầu, thấy pyrevit và vn-revit ở danh sách sau là xong. Mở cuộc trò chuyện mới và hỏi: “Kiểm tra kết nối Revit”.

4. Vẽ trên Revit bằng Claude

4.1. Quy trình một lần dựng

 1. Bạn đưa yêu cầu: mô tả, ảnh, PDF hoặc DWG mặt bằng
 2. Claude đọc get_context (Revit nào, mô hình nào, chế độ ask chưa)
 3. Claude tra loại tường, sàn, cửa, tầng có sẵn trong mô hình
 4. Claude ghi số liệu mặt bằng (mm) vào nha_pho_mau.py trong thư mục workspace, chạy kiem_tra()
 5. Mỗi chặng: chạy thử (dry run) → báo số phần tử → chạy thật → bạn bấm Keep / Discard trong Revit
 6. Claude chụp ảnh 3D, mặt bằng để tự kiểm
 7. Claude gọi vn-revit-mcp đối chiếu khối lượng với số liệu ban đầu

Thứ tự chặng: tầng → tường → phòng → sàn → cửa đi, cửa sổ → cột, dầm, mái, cầu thang. Mỗi chặng là một mục Undo riêng; chặng sau lỗi không làm mất chặng trước. Mọi phần tử Claude tạo đều được ghi Comments dạng vn: để chạy lại chặng đó mà không bị trùng.

4.2. Câu lệnh mẫu

Dựng từ mô tả:

Dùng skill ve-revit. Dựng nhà phố 2 tầng trên lô 5x15 m trong mô hình Revit đang mở:
tầng cao 3600, tường bao 200, tường ngăn 100. Tầng 1: phòng khách phía trước sâu 6 m, bếp ăn,
cuối nhà WC và kho. Tầng 2: hai phòng ngủ. Cửa chính rộng 2400 ở mặt tiền.
Làm từng chặng, chạy thử trước, chờ tôi bấm Keep rồi mới làm chặng sau.

Dựng từ bản vẽ AutoCAD:

Dùng skill ve-revit. Đọc mặt bằng tầng 1 và tầng 2 trong D:\DuAn\NhaPho\KT-02.pdf (hoặc file .dwg).
Ghi số liệu vào D:\DuAn\revit-workspace\nha_pho_mau.py, chạy kiem_tra(), báo tôi chỗ bản vẽ lệch
trước khi dựng. Chưa dựng gì khi tôi chưa duyệt bảng số liệu.

Sửa một phần:

Dùng skill ve-revit. Dời cửa D2 tầng 1 sang phải 300 mm và đổi sang cửa 800x2200.
Chạy thử, báo trước khi chạy thật.

Kiểm sau khi dựng:

Dùng vn-revit: tổng chiều dài tường 200 và 100 từng tầng, diện tích từng phòng,
số cửa theo kích thước. So với nha_pho_mau.py và báo chỗ lệch.

4.3. Dữ liệu mặt bằng trong workspace

Claude không dán lại số liệu vào mỗi đoạn code. Số liệu nằm trong một file Python ở thư mục workspace, mỗi lần chạy pyRevit nạp lại file đó. Bạn mở nha_pho_mau.py bằng Notepad là đọc được:

TANG = [("Tang 1", 0), ("Tang 2", 3600), ("Mai", 7200)]

TUONG = [
    {"ten": "T1-truoc", "tu": (0, 0), "den": (5000, 0), "day": 200, "tang": "Tang 1", "den_tang": "Tang 2"},
    ...
]
CUA = [
    {"loai": "cua_di", "ky_hieu": "D1", "tuong": "T1-truoc", "vi_tri": (2500, 0), "rong": 2400, "cao": 2600, "cao_be": 0},
    ...
]

• Đơn vị mm, gốc tọa độ tại giao trục góc trước bên trái, trục x dọc mặt tiền, trục y vào sâu.
• Tường ghi theo trục tường. Cửa ghi tọa độ điểm giữa cửa nằm trên trục tường.
• kiem_tra() báo lỗi trước khi dựng: tầng không có, tường dài bằng 0, cửa lệch trục tường, cửa quá sát chỗ giao tường (Revit cần ít nhất nửa bề rộng cửa cộng 152 mm), số phòng trùng.
• File mẫu là nhà phố mẫu 5x15 m, chỉ để minh họa cách ghi, không phải công trình thật.

4.4. Công cụ của MCP pyRevit

Theo tài liệu pyRevit 7 (docs/agent-runtime.md):

4.5. Giới hạn cần biết

• Family phải có sẵn trong mô hình. Không có cửa đúng kích thước, Claude sẽ hỏi bạn nạp family hoặc nhân bản type. Skill không tự tải family từ Internet.
• Tên loại khác nhau giữa các template. Claude luôn tra tên trong mô hình, không dùng tên nhớ sẵn.
• Cầu thang, mái phức tạp dễ lỗi hơn tường, sàn. Nên dựng riêng, kiểm kỹ.
• Mô hình dựng theo dữ liệu, không thay kiến trúc sư, kỹ sư. Hồ sơ xin phép, thi công phải được người có chứng chỉ kiểm tra.

5. Thống kê và khối lượng

Số liệu đổi từ đơn vị nội bộ của Revit (feet) sang m, m², m³, mm. Tổng tính trên số đầy đủ, chỉ làm tròn 2 chữ số khi hiển thị.

Câu hỏi mẫu:

• “Mô hình đang mở có bao nhiêu cửa đi, cửa sổ? Chia theo tầng.”
• “Tổng diện tích phòng từng tầng? Có phòng nào chưa khép kín không?”
• “Cửa nào chưa có Mark?”
• “Xuất bảng khối lượng ra Excel vào D:\DuAn\NhaPho\KhoiLuong.”
• “Chạy thử: ghi Comments = ‘Kiểm tra PCCC’ cho các cửa id 12345, 12346.”

File Excel:

• Lưu vào thư mục bạn chọn, hoặc Documents\vn-revit-mcp nếu không chọn. Tên 01_khoi-luong-revit-.xlsx, số tăng dần, không bao giờ ghi đè.
• Sheet KhoiLuong: STT, Mã hiệu, Tên công việc, Đơn vị, Diễn giải, KL thiết kế, Hao hụt (%), KL hao hụt, KL mua, Nguồn. Ô Hao hụt (%) để trống, tô vàng cho kỹ sư điền; KL hao hụt và KL mua tự tính bằng công thức. Mã hiệu ghi [Chờ bổ sung]. Dòng nào Revit không trả khối lượng thì Diễn giải ghi “Cần xác nhận lại”.
• Sheet chi tiết Tuong, San, KetCau, Cua, Phong; sheet Nguon ghi mô hình, bản Revit, thời điểm trích và các lưu ý.
• Khối lượng phụ thuộc cách dựng mô hình. Phần giao giữa các cấu kiện chưa join bị tính hai lần. Luôn đối chiếu bản vẽ trước khi dùng cho hợp đồng.

6. An toàn và dữ liệu

Phần A (vẽ) chạy code do AI viết, có toàn quyền như tài khoản Windows của bạn. pyRevit bảo vệ mô hình (gom thay đổi, chặn lưu file trong lúc chạy, hỏi Keep / Discard) nhưng không phải hộp cát: đoạn code vẫn đọc, ghi được file trên máy. Vì vậy:

• Chỉ dùng với AI client bạn tin cậy. Không đưa cho Claude tài liệu lạ có chứa câu lệnh (file tải từ nguồn không rõ, email lạ) rồi để nó dựng mô hình.
• Giữ chế độ ask. Đọc tóm tắt chạy thử trước khi bấm Keep.
• Làm trên bản sao mô hình khi mới dùng.

Phần B (thống kê):

• Không có công cụ chạy code tùy ý: chỉ 9 script cố định, đã kiểm thử.
• Tham số AI truyền vào đều bị kiểm: id là số nguyên dương, tối đa 200; tên tham số tối đa 120 ký tự; hạng mục phải là OST_... hoặc tên trong danh sách; chỉ gọi pyrevit.exe, không gọi file .bat, .cmd.
• Tên lấy từ mô hình không bao giờ được ghi thành công thức trong Excel.

Chung cho cả hai phần:

• Không mở cổng mạng. Lệnh pyrevit nói chuyện với Revit qua đường ống nội bộ chỉ tài khoản Windows của bạn dùng được.
• Dữ liệu mô hình đi ra ngoài máy. Những gì công cụ trả về (tên loại, tầng, tham số…) được gửi tới nhà cung cấp mô hình AI bạn đang dùng. Kiểm tra quy định bảo mật của dự án trước khi dùng với hồ sơ khách.
• pyRevit lưu lại từng lần chạy. Script, đầu vào, kết quả, ảnh chụp được lưu dạng văn bản rõ trong %APPDATA%\pyRevit\agent, tối đa 14 ngày.

Báo lỗ hổng bảo mật: xem SECURITY.md.

7. Xử lý lỗi

8. Gỡ cài đặt

claude mcp remove vn-revit -s user
pyrevit mcp uninstall claude
pyrevit configs agent disable

Skill nằm ở %USERPROFILE%\.claude\skills\ve-revit và %APPDATA%\pyRevit\agent\skills\ve-revit; muốn bỏ thì xóa hai thư mục này bằng tay.

9. Phát triển

git clone https://github.com/andyluu98/vn-revit-mcp
cd vn-revit-mcp
uv sync
uv run pytest

Kiểm thử tự kiểm cú pháp IronPython 2.7, ký tự ASCII của script và workspace, tính nhất quán của dữ liệu mẫu, và việc cài skill không bao giờ xóa bản cũ.

10. Liên quan đến pyRevit và nguồn tham khảo

vn-revit-mcp là dự án độc lập, không thuộc pyRevitLabs. Dự án gọi lệnh pyrevit đã cài trên máy và không chép mã nguồn của pyRevit. pyRevit có giấy phép GPL-3.0 riêng; vn-revit-mcp dùng giấy phép MIT.

Nguồn (tra ngày 16/10/2026, bản pyRevit v7.0.0.26278+2233 phát hành 06/10/2026):

• Agent runtime, công cụ MCP, cấu hình, giới hạn: docs/agent-runtime.md trong repo pyrevitlabs/pyRevit
• Skill gốc dựng mô hình: pyrevitlib/pyrevit/agent/skills/modeling/SKILL.md
• Hàm dựng create_wall, create_floor, create_room, place_hosted_instance: pyrevitlib/pyrevit/revit/db/create.py
• Lệnh pyrevit agent run và dạng JSON trả về: dev/pyRevitLabs/pyRevitCLI/PyRevitCLIAgentCmds.cs, dev/pyRevitLabs.PyRevit.Runtime/Agent/AgentRunService.cs
• pyRevit Releases