robot-structural-mcp

MCP server cho Autodesk Robot Structural Analysis Professional. Cho phép trợ lý AIđọc mô hình và kết quả phân tích trực tiếp từ phiên Robot đang mở.

Khác với Revit, Robot không cần add-in: Robot.Application là COM server ngoàiprocess, nên chỉ cần cài Python là chạy. Không phải build DLL, không cần quyền admin.

Yêu cầu

Windows + Autodesk Robot Structural Analysis Professional (kiểm thử trên bản 2027)
Python 3.11+ và uv
Robot đang chạy và đã mở một mô hình — server gắn vào instance đang chạyqua GetActiveObject, nó không tự khởi động Robot

Cài đặt

git clone https://github.com/<user>/robot-structural-mcp.git
cd robot-structural-mcp
.\install.ps1

install.ps1 tạo virtualenv, cài phụ thuộc và ghi cấu hình MCP vào ~/.claude.json.Khởi động lại Claude sau khi cài.

Cấu hình thủ công nếu muốn:

{
  "mcpServers": {
    "robot": {
      "type": "stdio",
      "command": "<repo>\\.venv\\Scripts\\python.exe",
      "args": ["-m", "robot_mcp"],
      "env": { "ROBOT_MCP_MAX_ITEMS": "200" }
    }
  }
}

An toàn: mặc định chỉ-đọc

Server không sửa mô hình trừ khi bạn cho phép rõ ràng. Các tool ghi(robot_save, robot_open_model) sẽ từ chối cho tới khi đặt:

ROBOT_MCP_ALLOW_WRITE=1

robot_run_calculation không nằm dưới cờ này vì nó không sửa mô hình, nhưng nó ghi đèkết quả và chạy lâu, nên bắt buộc truyền confirm=true.

Đơn vị — đọc kỹ phần này

RobotOM luôn trả về đơn vị SI (m, N, N·m, Pa, rad) bất kể giao diện Robot đang hiểnthị gì. Lấy thẳng số đó rồi coi như đơn vị trên màn hình là cách sai hệ số 1000 mà nhìnvẫn hợp lý — nguy hiểm nhất trong tính toán kết cấu.

Vì vậy mọi kết quả trả về đều kèm khối units tường minh, và được quy đổi quarobot_mcp/units.py. Mặc định: kN, kNm, m, mm (chuyển vị), MPa.

Đổi bằng tool robot_units hoặc biến môi trường ROBOT_MCP_UNIT_FORCE,ROBOT_MCP_UNIT_MOMENT, ROBOT_MCP_UNIT_LENGTH, ROBOT_MCP_UNIT_DISPLACEMENT,ROBOT_MCP_UNIT_STRESS.

Tools

Kết nối & dự án

Tool	Việc
`robot_status`	Kiểm tra kết nối, tên/đường dẫn mô hình, số lượng đối tượng, kết quả đã có chưa
`robot_units`	Xem/đổi đơn vị đầu ra
`robot_save`	Lưu mô hình — WRITE
`robot_open_model`	Mở file .rtd khác — WRITE

Mô hình

Tool	Việc
`robot_model_summary`	Tổng quan: số lượng, bounding box, danh sách tiết diện/vật liệu/gối
`robot_list_nodes` / `robot_get_node`	Nút và toạ độ
`robot_list_bars` / `robot_get_bar`	Thanh: nút đầu/cuối, chiều dài, tiết diện, vật liệu, release
`robot_list_panels`	Tấm
`robot_list_sections` / `robot_list_materials`	Nhãn tiết diện / vật liệu
`robot_list_supports` / `robot_list_releases`	Nhãn gối, release và đối tượng mang nhãn

Tải trọng

Tool	Việc
`robot_list_load_cases`	Toàn bộ trường hợp tải và tổ hợp
`robot_list_combinations`	Chỉ tổ hợp, kèm case thành phần và hệ số
`robot_get_load_records`	Các bản ghi tải trong một case

Phân tích

Tool	Việc
`robot_calculation_status`	Kết quả đã sẵn sàng chưa, trạng thái lần tính cuối
`robot_run_calculation`	Chạy phân tích (cần `confirm=true`)

Kết quả

Tool	Việc
`robot_get_bar_forces`	Nội lực dọc thanh (FX/FY/FZ, MX/MY/MZ) theo vị trí tương đối 0–1
`robot_get_bar_extreme_forces`	Bao nội lực min/max từng thành phần, kèm vị trí xảy ra
`robot_get_node_displacements`	Chuyển vị và góc xoay
`robot_get_node_reactions`	Phản lực gối — đầu vào cho thiết kế móng

Phát triển

Tool	Việc
`robot_inspect`	Duyệt chỉ-đọc cây đối tượng RobotOM để tìm API chưa được bọc

Chọn đối tượng

Các tool nhận selection theo cú pháp gốc của Robot: "1 3 5to9", "all","1to100by2". Bỏ trống thì lấy tất cả. Nhờ vậy truy vấn bám sát thói quen dùng Robotthay vì phải liệt kê số hiệu.

Phân trang

Mô hình vài chục nghìn phần tử sẽ làm vỡ context nếu đọc hết một lần. Mọi tool liệt kêđều có limit/offset và bị chặn trên bởi ROBOT_MCP_MAX_ITEMS (mặc định 200).Kết quả trả về luôn có cờ truncated.

Ghi chú thiết kế

Một thread STA duy nhất. Robot chỉ trả lời trên thread đã khởi tạo COM apartment,còn MCP runtime gọi tool trên thread bất kỳ. Toàn bộ lời gọi được dồn qua _Workertrong com.py.
Hằng số lấy từ type library, không viết theo trí nhớ. I_OT_BAR=1,I_LT_BAR_SECTION=3… được đọc trực tiếp từ robotom.tlb bằng makepy. Sai một hằngsố ở đây là số liệu sai âm thầm.
Kết quả kiểm tra trước khi đọc. Mọi tool kết quả kiểm Results.Available trước,nếu chưa tính thì báo lỗi rõ ràng thay vì trả số cũ.
Tắt cửa sổ tiến trình trước khi Calculate() — hộp thoại modal của Robot sẽ chặntoàn bộ COM nếu để bật.

Lộ trình

Giai đoạn 2 (cầu nối thiết kế): export_bar_forces_table, get_design_envelope,export_reactions_table, get_required_reinforcement, get_steel_design_results.

Giai đoạn 3 (dựng mô hình): tạo/sửa nút, thanh, tấm, gối, tải, tổ hợp.

Giấy phép

MIT

robot-structural-mcp