hj-pr-proposal

Revit MCP - AI-Powered Revit Control

English | 繁體中文

Revit MCP 透過 Model Context Protocol (MCP) 讓 AI Client 呼叫 Revit 工具，並由 Revit Add-in 在本機執行 Revit API 工作流程。

• 示範影片：Revit MCP - AI 驅動的 BIM 工作流程示範
• 知識站：https://shuotao.github.io/REVIT_MCP_study/
• 預設 WebSocket port：8964

目前專案狀態

項目	數量	來源
Runtime MCP tools	96	MCP-Server/src/tools/index.ts 的 registerRevitTools()
Domain SOP files	45	domain/*.md 扣除 README.md，加上 domain/references/*.md
Claude skills	22	.claude/skills/*/SKILL.md

如果這些數字改變，請同步更新 CLAUDE.md、本 README、README.en.md、docs/DOCUMENT_AUDIENCE_INVENTORY.md，並執行：

.\scripts\verify-qaqc.ps1 -SkipBuild -SkipDeploy

架構

AI Client
  Claude Desktop / Claude Code / Gemini CLI / VS Code Copilot / Antigravity
        |
        | stdio
        v
MCP Server
  Node.js / TypeScript
  MCP-Server/build/index.js
        |
        | WebSocket ws://localhost:8964
        v
Revit Add-in
  C# / Revit API
  MCP/Application.cs
  MCP/Core/SocketService.cs
  MCP/Core/ExternalEventManager.cs
        |
        v
Autodesk Revit

外部 AI Client 不需要在本專案內設定 AI API Key；AI 帳號與授權由各 AI Client 自己管理。只有「Revit 內嵌 AI Chat」這種直接呼叫 AI API 的方案才需要 API Key。

系統需求

項目	需求
OS	Windows 10 或更新版本
Revit	Autodesk Revit 2022、2023、2024、2025、2026
.NET	Revit 2022-2024 使用 .NET Framework 4.8；Revit 2025-2026 使用 .NET 8
Node.js	LTS，建議 20.x 或更新版本

一鍵安裝

新手建議使用：

.\scripts\setup.ps1

AI Agent 或非互動模式可使用：

powershell -ExecutionPolicy Bypass -File scripts/setup.ps1 -NonInteractive -RevitVersions "2024,2025"

腳本會檢查環境、安裝相依套件、編譯 MCP Server、編譯並部署 Revit Add-in，並協助設定常見 AI Client。

手動安裝

1. 編譯 MCP Server

cd MCP-Server
npm install
npm run build

AI Client 會啟動：

node MCP-Server/build/index.js

2. 編譯 Revit Add-in

請依 Revit 版本選擇設定：

cd MCP
dotnet build -c Release.R22 RevitMCP.csproj   # Revit 2022
dotnet build -c Release.R23 RevitMCP.csproj   # Revit 2023
dotnet build -c Release.R24 RevitMCP.csproj   # Revit 2024
dotnet build -c Release.R25 RevitMCP.csproj   # Revit 2025
dotnet build -c Release.R26 RevitMCP.csproj   # Revit 2026

輸出路徑是：

MCP/bin/Release.R{YY}/RevitMCP.dll

例如 Revit 2024：

MCP/bin/Release.R24/RevitMCP.dll

3. 部署 Add-in

建議使用：

.\scripts\install-addon.ps1

手動部署時，.addin 與 DLL 必須放在對應版本的 Revit Addins 位置，並維持 RevitMCP.addin 內的相對 assembly path：

<Assembly>RevitMCP\RevitMCP.dll</Assembly>

不要建立版本專屬 .addin，也不要硬寫絕對 DLL 路徑。

AI Client 設定

本專案已有 Claude Code / Codex 風格的 .mcp.json：

{
  "mcpServers": {
    "revit-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["./MCP-Server/build/index.js"],
      "env": {}
    }
  }
}

VS Code 設定在 .vscode/mcp.json：

{
  "servers": {
    "revit-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["${workspaceFolder}/MCP-Server/build/index.js"],
      "env": {}
    }
  }
}

其他 AI Client 的核心概念相同：使用 node 啟動 MCP-Server/build/index.js。

各 Client 的設定範本對照：

AI Client	設定位置	範本
Claude Code	專案根目錄 .mcp.json	已內建，開箱即用
Claude Desktop	%APPDATA%\Claude\claude_desktop_config.json	MCP-Server/claude_desktop_config.json
Gemini CLI	~/.gemini/settings.json	MCP-Server/gemini_mcp_config.json
VS Code Copilot	.vscode/mcp.json	已內建
Antigravity	UI 設定	Antigravity_MCP_Complete_Guide.md

範本中的 <YOUR_PROJECT_PATH> 需替換為本專案的實際路徑。

AI Client 切換與並用限制

Revit 端的 WebSocket 服務一次只接受一條 MCP 連線：後連上的 MCP Server 會取代先前的連線。因此多個 AI Client 是「切換使用」而不是「同時並用」：

1. 關閉目前使用的 AI Client（或停用其 MCP server）。
2. 啟動另一個 AI Client，它的 MCP Server 連上 localhost:8964 後即接手。
3. 若連線狀態異常，於 Revit ribbon 重啟 MCP 服務即可重置。

啟動流程

1. 啟動 Revit。
2. 載入或建立專案。
3. 在 Revit ribbon 的 MCP Tools 面板啟動 MCP 服務。
4. 確認 Revit 顯示 WebSocket server 已監聽 localhost:8964。
5. 啟動或重啟 AI Client，讓它載入 MCP Server。
6. 在 AI Client 中呼叫 Revit MCP tools。

如果 localhost:8964 連不上，通常代表 Revit 沒開、MCP 服務沒開、port 被佔用，或 AI Client 的 REVIT_MCP_PORT 與 Revit 端設定不一致。

專案結構