Revit MCP

Revit MCP - AI 驱动的 Revit 控制

English | 繁體中文

Revit MCP 让 AI 客户端能够通过模型上下文协议（MCP）调用 Autodesk Revit 工具。MCP 服务会将工具调用转发到本地 Revit 插件，由插件执行相应的 Revit API 工作流。

• 演示视频：Revit MCP - AI 驱动的 BIM 工作流演示
• 知识网站：https://shuotao.github.io/REVIT_MCP_study/
• 默认 WebSocket 端口：8964

这是什么？

用日常语言与 Revit 对话。让 AI 客户端帮你“标注此视图中的每面墙”或“检查幕墙立面”，Revit 就会执行——通过 239 个 MCP 工具和 90 个专业 BIM SOP（建筑规范、工程量清单、合规检查）实现。

适用对象： 使用 Revit 并希望采用 AI 辅助、基于标准的工作流的 BIM 工程师和建筑师。你需要在 Windows 上安装 Revit（2022–2026），并熟悉插件安装。

快速入门（3 步）

1. 安装 Revit 插件。 构建并部署 C# 插件——请参阅手动设置。这是实际与 Revit 通信的部分。
2. 将 AI 客户端指向 MCP 服务。 无需克隆——直接通过 npm 运行：

   { "mcpServers": { "revit-mcp": { "command": "npx", "args": ["-y", "@shuotao/revit-mcp-server"] } } }
   

3. 打开 Revit，在功能区中启用 MCP 服务，然后开始提问。 完整设置说明：AI 客户端配置。

有问题或想展示你的成果？→ 讨论区

当前项目统计

项目	数量	来源
运行时 MCP 工具	239	registerRevitTools() 位于 MCP-Server/src/tools/index.ts
领域 SOP 文件	94	domain/*.md（不含 README.md），以及 domain/references/*.md
Claude 技能	61	.claude/skills/*/SKILL.md

这些数字发生变化时，请更新 CLAUDE.md、README.zh-TW.md、本文档、docs/DOCUMENT_AUDIENCE_INVENTORY.md，并运行：

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

新增：交互式碰撞查看器（MCP Apps）

现在，detect_clashes 可通过 MCP Apps 扩展（io.modelcontextprotocol/ui）在对话中直接呈现交互式碰撞审查界面。这需要支持该扩展的 MCP 主机。这项功能仅作增补，不会影响现有功能：

• 只有支持 MCP Apps 的 图形界面主机（Claude Desktop、claude.ai 网页应用、VS Code GitHub Copilot）才会进行交互式渲染。像 Claude Code 这样的终端命令行无法渲染面板，始终会显示文本结果——这是预期行为，并非故障。
• 不支持 MCP Apps 的主机仍会收到 detect_clashes 的常规文本结果——它们不会有任何变化。
• stdio 连接和现有 Revit 插件不受影响；无需重新安装或重新配置。

完整的 MCP 2026-07-28 升级说明请参阅 docs/MIGRATION_GUIDE.md。

架构

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 客户端无需在此代码库中使用 API 密钥。其账户和授权由 AI 客户端自身管理。只有直接调用 AI API 的内嵌 Revit 聊天功能才需要 API 密钥。

要求

项目	要求
操作系统	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 服务、构建并部署 Revit 插件，并帮助配置常见 AI 客户端。

从 MCP Registry 安装

MCP 服务已发布到 MCP Registry，名称为 io.github.shuotao/revit-mcp-server（npm 包 @shuotao/revit-mcp-server）。运行方式：

npx -y @shuotao/revit-mcp-server

注意：此 npm 包仅提供 Node stdio 桥接程序。仍需单独安装 C# Revit 加载项（MCP/）——请根据 Revit 版本参阅下方的手动设置。

手动设置

1. 构建 MCP 服务

cd MCP-Server
npm install
npm run build

AI 客户端启动命令：

node MCP-Server/build/index.js

2. 构建 Revit 加载项

选择与 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. 部署加载项

推荐方式：

# Pick the Revit version explicitly. With several installed and no -Version, the script asks;
# in -NonInteractive mode it fails rather than guessing (it never silently picks the highest).
.\scripts\install-addon.ps1 -Version 2024

# Deploy to every installed version that has a matching build
.\scripts\install-addon.ps1 -All

该脚本会复制构建输出中的所有 DLL（R22-R24 为 13 个，R25-R26 为 8 个——两种情况均正确）， 在复制前检查构建代次是否与目标 Revit 匹配，之后通过 SHA256 校验每个文件， 并轮换旧备份。

如需手动部署，请将 .addin 文件和 DLL 放在对应的 Revit Addins 目录下，并在 RevitMCP.addin 中保留相对程序集路径：

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

不要创建特定版本的 .addin 文件，也不要硬编码绝对 DLL 路径。

AI 客户端配置

项目级 .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 客户端使用相同的方式：通过 node 启动 MCP-Server/build/index.js。

各客户端的配置模板：

AI 客户端	配置位置	模板
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 客户端之间切换

Revit 端的 WebSocket 服务会持有独占锁：一次只能连接一个 AI 客户端。第二个尝试连接的客户端会被正常拒绝（HTTP 409），而不会替换当前客户端——第一个连接会保持稳定。因此，多个 AI 客户端应通过切换使用，而非同时连接：

在执行锁检查之前，任何携带浏览器 Origin 标头的握手都会被直接拒绝，并返回 HTTP 403。这可防止另一类风险：否则，浏览器中打开的恶意页面可能会在你不知情的情况下驱动加载项，因为 WebSocket 握手不受浏览器同源策略约束。此设置无法通过配置关闭，且不会影响 MCP 桥接程序，因为它不会发送 Origin 标头。

1. 在 Revit 功能区中，点击**“切換/釋放連線”（切换/释放连接）**按钮以释放当前连接。
2. 启动或重新连接另一个 AI 客户端；其 MCP 服务连接到 localhost:8964 后，即会获取锁。
3. **“MCP 設定”**对话框会显示当前持有连接的客户端（例如 claude-code、claude-ai）。
4. 如果连接异常，请使用同一个功能区按钮，或从 Revit 功能区重启 MCP 服务以重置连接。

启动流程

1. 启动 Revit。
2. 打开或创建 Revit 项目。
3. 从 Revit 功能区启用 MCP 服务。
4. 确认 Revit 加载项正在 localhost:8964 上监听。
5. 启动或重启 AI 客户端，使其加载 MCP 服务。
6. 在 AI 客户端中调用 Revit MCP 工具。

如果无法访问 localhost:8964，可能是 Revit 未运行、MCP 服务未启用、端口被占用，或 AI 客户端与 Revit 加载项使用了不同的端口设置。

项目结构

REVIT_MCP/
  MCP/                         Revit Add-in (C#)
    Application.cs             Revit add-in entry point
    RevitMCP.csproj            Single multi-version project
    RevitMCP.addin             Single add-in manifest
    Core/
      SocketService.cs         Revit-side WebSocket server
      ExternalEventManager.cs  UI-thread execution bridge
      RevitCompatibility.cs    Revit 2022-2026 compatibility helpers
      CommandExecutor.cs       Main command dispatcher
      Commands/*.cs            Command modules
  MCP-Server/                  MCP Server (Node.js / TypeScript)
    src/index.ts               stdio MCP server entry
    src/socket.ts              WebSocket client to Revit
    src/tools/*.ts             MCP tool definitions
  domain/                      Shared BIM SOPs; do not convert to English-only
  .claude/                     AI commands and skills
  docs/                        Human-facing docs and public knowledge site
  scripts/                     Setup, deployment, QA/QC scripts
  log/                         Append-only session and commit logs

AI 文档与人工文档

类型	位置	规则
仅供 AI 使用	CLAUDE.md、.claude/commands/、.claude/skills/	优先使用英文，避免出现乱码
面向人工读者	README.md、README.zh-TW.md、docs/、scripts/README.md	与读者使用的语言一致
共用	domain/*.md、log/README.md	Domain 文件必须保持中文可读，不得仅使用英文
历史文档	docs/_archive/**、旧日志	默认保留

参见 docs/DOCUMENT_AUDIENCE_INVENTORY.md。

Domain、Skill 与工具的职责

• domain/*.md：BIM 标准作业程序、法规逻辑和计算方法。供人工和 AI 共用。
• .claude/skills/*/SKILL.md：AI 工作流编排。
• MCP-Server/src/tools/*.ts：MCP 工具定义和输入架构。
• MCP/Core/Commands/*.cs：Revit API 实现。

如果 Domain 文件与 Skill 的方法不一致，以 Domain 文件为准。

QA/QC

完成文档、工具、Domain、Skill、构建或部署变更后，运行：

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

部署前，运行完整检查：

.\scripts\verify-qaqc.ps1 -Version 2024

QA/QC 检查项：

• 禁止使用的旧文件和路径
• 必需的文件结构
• README / CLAUDE / docs 数量一致性
• Domain 表格的正向与反向覆盖
• 本地 Markdown 链接失效情况
• Domain frontmatter
• 文档受众分类
• 规范文档中的乱码风险

故障排除

AI 无法找到 Revit 工具

检查：

1. 是否已在 MCP-Server 中运行 npm run build。
2. AI 客户端的 MCP 配置是否指向正确的 MCP-Server/build/index.js。
3. 是否已重启 AI 客户端或重新加载 MCP 服务。

MCP Server 无法连接 Revit

检查：

1. Revit 是否正在运行。
2. Revit 功能区中的 MCP 服务是否已启用。
3. localhost:8964 是否被占用。
4. 如果 HTTP.sys / PID 4 正占用该端口，请尝试：

powershell -ExecutionPolicy Bypass -File scripts\release-port.ps1

Revit 未显示 MCP Tools 面板

确认 .addin 文件和 DLL 已部署到对应的 %APPDATA%\Autodesk\Revit\Addins\{version} 目录下，然后重启 Revit。

重要规则

• 保留一个 MCP/RevitMCP.csproj。
• 保留一个 MCP/RevitMCP.addin。
• 不要创建特定版本的 .csproj 或 .addin 文件。
• 不要创建嵌套的 MCP/MCP/ 目录。
• 不要将 .addin 中的 <Assembly> 改为绝对路径。
• 不要将 Domain 文件改为仅使用英文。
• 不要通过手写 WebSocket JSON 绕过 MCP 服务。
• 对于 Revit 当前视图、标高、选择或文档状态，AI 必须在当前轮次查询实时状态。

文档导航

文档	用途
CLAUDE.md	AI Agent 主纲领和项目概览
AGENTS.md	重定向至 CLAUDE.md
GEMINI.md	重定向至 CLAUDE.md
README.zh-TW.md	繁体中文 README
CONTRIBUTING.md	贡献指南
CHANGELOG.md	发布历史
domain/README.md	Domain 标准作业程序目录
domain/lessons.md	项目经验
.claude/skills/	AI 技能
.claude/commands/	AI 斜杠命令
scripts/README.md	脚本文档
docs/DOCUMENT_AUDIENCE_INVENTORY.md	文档受众清单
docs/DOCS_STRUCTURE.md	Docs 目录指南
log/README.md	日志追加规则

许可证

MIT 许可证