NavisworksMCP

AI 驅動的 Navisworks 自動化控制系統 透過 Model Context Protocol (MCP) 讓 Claude、Gemini、VS Code Copilot 等 AI 平台直接操控 Autodesk Navisworks。

---

系統架構

┌──────────────┐      stdio       ┌──────────────┐    WebSocket     ┌──────────────────┐
│  AI 平台      │ ◄──────────────► │  MCP Server  │ ◄──────────────► │  Navisworks 插件  │
│  Claude       │     MCP 協議     │  (Node.js)   │    port 2233    │  (C# Add-in)     │
│  Gemini       │                  │              │                  │                  │
│  VS Code      │                  │  index.ts    │                  │  Application.cs  │
└──────────────┘                  └──────────────┘                  └──────────────────┘

三層分離設計：

• AI 平台 — 發送自然語言指令，由 MCP 協議轉譯為工具呼叫
• MCP Server — Node.js/TypeScript 中繼層，管理 WebSocket 連線與命令路由
• Navisworks Add-in — C# Plugin，在 NW 主執行緒中安全執行 .NET API 操作

---

快速開始

環境需求

項目	版本
Navisworks Manage	2025
.NET Framework	4.8
Node.js	20+ LTS
Visual Studio	2019+

安裝步驟

# 1. 一鍵安裝 MCP Server 依賴並編譯
scripts\setup.bat

# 2. 在 Visual Studio 開啟解決方案
#    → 確認 NavisworksMCP.csproj 中的 NavisworksPath 正確
#    → Build Release

# 3. 部署 Plugin（需要管理員權限）
powershell -ExecutionPolicy Bypass -File scripts\install-addon.ps1

啟動服務

1. 開啟 Navisworks Manage 2025
2. 載入你的 NWF/NWD 模型
3. 在 Add-ins 面板找到 "MCP 服務 (開/關)" 按鈕，點擊啟動
4. 看到提示 WebSocket 端口: 2233 即表示服務就緒

連接 AI 平台

VS Code / Claude Code： 已配置 .vscode/mcp.json，開箱即用

Claude Desktop： 在設定中加入：

{
  "mcpServers": {
    "navisworks": {
      "command": "node",
      "args": ["C:/Users/你的帳號/DESKTOP/NV_mcp/MCP-Server/build/index.js"],
      "env": { "NAVIS_MCP_PORT": "2233" }
    }
  }
}

---

使用模式

NavisworksMCP 提供 27 個工具，設計為五步驟工作流程：

Step 1 — 了解模型

「這個模型有什麼？裡面有幾個來源檔案？主要分類是哪些？」

get_document_info          → 文件名稱、單位、模型數量
get_model_info             → 各來源檔案的根節點與子項目數
get_model_statistics       → 按分類/圖層/來源檔案統計數量  ★ 核心工具
get_all_categories         → 列出所有屬性分類名稱
get_model_tree             → 展開模型樹結構（可指定深度）

典型對話：

用戶：「幫我分析一下這個模型的組成」
AI 呼叫：get_model_statistics(groupBy: "sourceFile")
         → 回傳：Architectural.nwc (3,200 items), MEP.nwc (1,800 items), Structure.nwc (950 items)
AI 呼叫：get_model_statistics(groupBy: "classDisplayName")
         → 回傳：Wall (420), Door (180), Pipe (650), Duct (320)...

---

Step 2 — 篩選與定位

「找出所有的門」「選擇 Selection Set 裡的機電管線」「用搜尋集過濾」

get_selection_sets         → 列出所有已儲存的選擇集
get_selection_set_items    → 讀取 Set 內容（不改變選擇）   ★ 安全讀取
execute_search_set         → 執行 Search Set 並回傳結果    ★ 搜尋集
search_items               → 自定義搜尋（按分類+屬性+值）
select_items_by_search     → 搜尋並選擇項目
select_items_by_set        → 選擇指定 Set 的所有項目
clear_selection            → 清除選擇

典型對話：

用戶：「模型裡有哪些選擇集？」
AI 呼叫：get_selection_sets
         → 回傳：MEP-Piping (Search Set, 650 items), Clash-Group-A (120 items)...

用戶：「看一下 MEP-Piping 裡面有什麼」
AI 呼叫：get_selection_set_items(name: "MEP-Piping", maxResults: 50)
         → 回傳項目清單（不影響當前選擇狀態）

用戶：「找出所有 Element 分類中 Type 是 Wall-200mm 的項目」
AI 呼叫：search_items(category: "Element", property: "Type", value: "Wall-200mm")

get_selection_set_items vs select_items_by_set 的差別：

工具	改變選擇？	用途
get_selection_set_items	不改變	安全探索，了解 Set 內容
select_items_by_set	改變	需要後續操作（上色、隱藏等）時使用

---

Step 3 — 偵測現有狀態

「哪些東西被隱藏了？有沒有被凍結的項目？模型的篩選狀態是什麼？」

get_override_status        → 綜合報告：隱藏/凍結概覽       ★ 狀態總覽
get_hidden_items           → 列出所有被隱藏的項目
get_frozen_items           → 列出所有被凍結的項目

典型對話：

用戶：「看看模型現在的篩選狀態」
AI 呼叫：get_override_status(scope: "all", maxResults: 50)
         → 回傳：隱藏 23 項、凍結 5 項，附帶路徑清單

用戶：「哪些管線被隱藏了？」
AI 呼叫：get_hidden_items(maxResults: 200)
         → 回傳所有隱藏項目的名稱、分類、路徑

---

Step 4 — 資料抽取

「把所有門的 ID 和高度匯出」「讀取選擇集的特定屬性」

get_item_properties        → 單項完整屬性（所有分類）
batch_get_properties       → 批量抽取，可指定欄位          ★ 資料匯出
get_item_geometry_info     → 幾何包圍盒與中心點座標

典型對話：

用戶：「把 MEP-Piping 選擇集裡所有管線的直徑和材質抽出來」
AI 呼叫：batch_get_properties(
           setName: "MEP-Piping",
           fields: ["Element.Diameter", "Element.Material"],
           maxResults: 500
         )
         → 回傳表格式資料，每列包含 displayName、path、指定欄位值

用戶：「看一下選中項目的完整屬性」
AI 呼叫：get_item_properties
         → 回傳所有分類 > 屬性名 > 值 > 資料類型

batch_get_properties 兩種模式：

模式	參數	說明
從 Selection Set	setName: "MEP-Piping"	直接讀取，不影響選擇
從當前選擇	不指定 setName	讀取 CurrentSelection

---

Step 5 — 視覺管理

「把管線標紅色」「隱藏結構柱」「切換到 3D 視點」

set_item_override_color    → 覆蓋選中項目的顯示顏色 (RGB)
clear_override_colors      → 清除顏色覆蓋（重設材質）
hide_items                 → 隱藏選中項目
unhide_all                 → 取消隱藏所有項目
zoom_to_selection          → 視圖對準選中項目
get_viewpoints             → 列出已儲存的視點
set_active_viewpoint       → 切換到指定視點
get_current_selection      → 確認當前選了什麼

典型對話：

用戶：「把碰撞區域的管線標成紅色」
AI 呼叫：select_items_by_set(name: "Clash-Group-A")
AI 呼叫：set_item_override_color(r: 255, g: 0, b: 0)
AI 呼叫：zoom_to_selection

用戶：「隱藏所有結構柱，只看機電」
AI 呼叫：search_items(category: "Element", property: "Category", value: "Structural Columns")
AI 呼叫：select_items_by_search(category: "Element", property: "Category", value: "Structural Columns")
AI 呼叫：hide_items

用戶：「恢復全部顯示」
AI 呼叫：unhide_all
AI 呼叫：clear_override_colors

---

完整工具清單

讀取工具（不改變模型狀態）— 17 個

工具	說明
get_document_info	文件基本資訊
get_model_info	來源模型清單
get_model_tree	模型樹結構
get_model_statistics	按分類/圖層/來源統計
get_all_categories	屬性分類名稱
get_current_selection	當前選擇清單
get_item_properties	單項屬性詳情
get_item_geometry_info	幾何包圍盒
get_selection_sets	選擇集清單
get_selection_set_items	選擇集內容（不選擇）
get_viewpoints	視點清單
get_clash_tests	碰撞測試清單
get_clash_results	碰撞結果詳情
get_override_status	隱藏/凍結狀態概覽
get_hidden_items	隱藏項目清單
get_frozen_items	凍結項目清單
batch_get_properties	批量屬性抽取

操作工具（會改變模型狀態）— 10 個

工具	改變什麼
search_items	不改變選擇，僅回傳結果
select_items_by_search	改變 CurrentSelection
select_items_by_set	改變 CurrentSelection
execute_search_set	可選擇是否改變 CurrentSelection
clear_selection	清空 CurrentSelection
set_active_viewpoint	切換視點
set_item_override_color	覆蓋顏色
clear_override_colors	重設材質
hide_items	隱藏項目
unhide_all	取消隱藏

---

工具組合範例

範例 1：模型初始分析

1. get_document_info                          → 了解基本資訊
2. get_model_statistics(groupBy: "sourceFile") → 看各來源檔案佔比
3. get_model_statistics(groupBy: "classDisplayName") → 看分類分佈
4. get_selection_sets                          → 看有哪些預設篩選
5. get_override_status(scope: "all")           → 看是否有已套用的篩選

範例 2：管線資料匯出

1. get_selection_sets                          → 找到 "MEP-Piping" 集
2. get_selection_set_items(name: "MEP-Piping") → 預覽內容
3. batch_get_properties(                       → 批量抽取指定欄位
     setName: "MEP-Piping",
     fields: ["Element.Id", "Element.Diameter", "Element.Material"]
   )

範例 3：碰撞項目視覺化

1. get_selection_sets                          → 找碰撞相關 Set
2. select_items_by_set(name: "Clash-Group-A")  → 選擇碰撞群組
3. set_item_override_color(r:255, g:0, b:0)    → 標紅色
4. zoom_to_selection                           → 對準畫面
5. get_item_properties                         → 看碰撞項目屬性

範例 4：隱藏非相關學科

1. get_model_statistics(groupBy: "sourceFile") → 確認有哪些來源
2. search_items(category: "Item", property: "Source File", value: "Structure.nwc")
3. select_items_by_search(同上參數)             → 選擇結構模型
4. hide_items                                  → 隱藏結構
5. unhide_all                                  → 完成後恢復

---

專案結構

NV_mcp/
├── NavisworksMCP.sln           # Visual Studio 解決方案
├── CLAUDE.md                   # AI 開發規範
├── README.md                   # 本文件
├── .gitignore
│
├── MCP/                        # C# Navisworks Add-in
│   ├── NavisworksMCP.csproj    # .NET Framework 4.8
│   ├── Application.cs          # Plugin 入口 (Toggle + Log + EventWatcher)
│   ├── Core/
│   │   ├── SocketService.cs    # WebSocket 服務 (port 2233)
│   │   ├── CommandExecutor.cs  # 27 個命令的執行器
│   │   ├── IdleEventManager.cs # 主執行緒安全排程
│   │   └── Logger.cs           # 日誌系統
│   └── Models/
│       ├── NavisCommandRequest.cs
│       └── NavisCommandResponse.cs
│
├── MCP-Server/                 # Node.js MCP Server
│   ├── package.json            # @modelcontextprotocol/sdk + ws
│   ├── tsconfig.json
│   └── src/
│       ├── index.ts            # MCP Server 入口 (stdio transport)
│       ├── socket.ts           # WebSocket 客戶端
│       └── tools/
│           └── navis-tools.ts  # 27 個工具定義
│
├── scripts/
│   ├── setup.bat               # 一鍵安裝
│   └── install-addon.ps1       # Plugin 部署
│
└── .vscode/
    └── mcp.json                # VS Code MCP 配置

---

注意事項

• WebSocket 端口固定為 2233，可透過環境變數 NAVIS_MCP_PORT 調整
• 所有命令在 Navisworks 主執行緒中序列化執行，不會有並發衝突
• Plugin DLL 部署到 C:\Program Files\Autodesk\Navisworks Manage 2025\Plugins\NavisworksMCP\
• 日誌存放在 %APPDATA%\NavisworksMCP\Logs\

授權

MIT License