RevitMCP：让智能体进入 Revit 建模

项目地址：https://github.com/CHMOSE023/RevitMCP

一、它是什么

在《智能体（Agent）入门》里我们说过：工具的设计决定了智能体能做什么。RevitMCP 就是给智能体准备的一套 Revit 工具。

装上插件、启动 Revit 之后，功能区会多出一个 RevitMCP 选项卡，Revit 进程里同时跑起一个 MCP 服务。Claude Code、Claude Desktop、Cline 这类支持 MCP 的客户端连上它，就能直接对 AI 说“把三层的内墙都换成 200 厚”“给这层的房间建明细表并导出 CSV”。

	说明
支持版本	Revit 2019 – 2024
工具数量	75 个：37 个只读 + 38 个写（含 2 个默认关闭的“逃生舱”）
接入方式	标准 MCP over HTTP，只监听本机，访问需令牌
架构	纯 C# 单进程：MCP 服务直接跑在 Revit 进程内，没有额外的桥接程序
依赖	零第三方运行时依赖，产物只有 4 个 DLL

最后一条看起来是技术洁癖，其实是被 Revit 逼出来的：Revit 把所有插件加载进同一个运行环境，插件各自带的第三方库版本一旦冲突，轻则功能失效，重则影响别的插件。所以 RevitMCP 连 JSON 解析都是自己写的。

二、能做什么

场景	典型工具	可以对 AI 说
看懂模型	revit_list_levels revit_query_elements revit_get_element_parameters	“这个模型有几层？每层有多少扇门？”
建模	revit_create_line_based_elements（墙、梁）、revit_create_point_based_elements（门窗柱家具）、revit_create_surface_based_elements（楼板屋顶天花）	“按这张草图建一圈外墙，再开 6 扇窗”
改模型	revit_set_element_parameters revit_change_element_types revit_transform_elements	“把所有防火门的注释改成 FM甲”
房间与空间	revit_create_rooms revit_list_rooms	“给每个房间建房间，面积为 0 的列出来”
出图	revit_create_views revit_create_sheets revit_add_views_to_sheet	“新建 A1 图纸，把一层平面摆上去”
交付导出	revit_export_documents revit_export_image revit_export_schedules	“导出所有图纸的 PDF 和一份 IFC”
质检	revit_get_warnings revit_check_clashes	“列出模型警告，查一下风管和梁有没有打架”
协同	revit_list_worksets revit_list_links revit_sync_to_central	“同步到中心文件”

只读工具可以同时查 Revit 里打开的多个模型，不必先切换活动文档——做批量审计时，智能体可以把十几个模型挨个过一遍，而不打断你正在看的视图。

三、一个例子：建错了，自己发现、自己改

RevitMCP 每个阶段的验收标准都不是“工具清单打勾”，而是一条能跑通的真实工作流。下面是其中一条的过程：

目标：建一圈外墙围出一个房间

思考：先查标高和墙类型，挑一个 200 厚的外墙
行动：revit_list_levels、revit_list_types
观察：拿到标高 1 的 ID 和墙类型 ID

思考：一圈墙一次调用传完，这样撤销时只算一步
行动：revit_create_line_based_elements（4 面墙）
观察：成功，但其中一面墙的端点写错了

思考：检查模型有没有问题
行动：revit_get_warnings
观察：出现墙体重叠的警告，并点名到具体构件 ID

思考：删掉错的那面墙——先看会连带删掉什么
行动：revit_delete_elements
观察：返回影响清单（包括墙上会被一起删掉的门窗），要求确认

行动：revit_delete_elements（confirm: true），重建这面墙
行动：revit_get_warnings
观察：干净了

行动：revit_set_selection，把结果选中交回给用户查看

全程不需要人按 Ctrl+Z。关键在于：智能体能看到自己操作的真实结果，模型警告、构件几何、删除影响都是结构化返回的，它可以据此判断和修正。

四、核心设计：把 Revit 的坑挡在工具里

1. 按几何形态分工具，一次调用建一批

建模工具不是“建墙”“建门”“建梁”一个个加，而是按几何形态分成三类：按线建（墙、梁）、按点建（门窗柱家具）、按闭合边界建（楼板屋顶天花）。具体建什么由类别和类型 ID 决定。因为门、窗、梁、板之间真正的差异，往往只是“调哪个 Revit API”那一行。

参数一律收数组：一次调用 = 一个事务 = 撤销栈里的一步，名字叫 MCP: <工具名>。批量建 200 面墙也只是一步；如果逐面调用建 11 面墙，用户就要按 11 次 Ctrl+Z。

尺寸由类型决定，不在实例上改：要 200 厚的墙，就用 revit_list_types 挑一个 200 厚的类型，而不是让 AI 随手新建一堆“墙-200-临时”之类的类型——类型库是用户的资产。

2. 写操作的三条保证

• 一步撤销：每个写调用在 Revit 里就是一个可撤销步骤，用户看得懂。
• 失败必回滚：无论是工具主动报错还是意外异常，模型都回到调用前的样子。
• 警告一定说出来：事务中的 Revit 警告会被自动忽略（否则弹出的对话框会把 Revit 和服务一起卡住），但每一条都会出现在返回结果里，带上构件 ID。静默吞掉警告比弹框更危险。

另外还有一道规模闸：一次影响超过 500 个构件，需要智能体显式确认才会执行。它防的不是“想改 600 个”，而是“以为在改 6 个、实际匹配到了 600 个”。

3. 删除先演练一遍

删一面墙，墙上的门窗会跟着没，而 Revit 没有提供“预演删除”的接口。RevitMCP 的做法是：在子事务里真删一次，记下 Revit 报告的完整影响面，然后回滚。子事务的回滚对用户完全不可见。

所以第一次调用删除，拿到的是一份真实的影响清单——包括你没点名、但会被连带删掉的构件——确认后才真正执行。代价是删除做了两遍，换来的是“确认”不再是走过场。

4. 超时之后，不用再赌

网络请求超时，最尴尬的问题是：到底建成了没有？ 直接重试可能建出两份，当作失败又可能漏掉。

RevitMCP 把失败分得很清楚：

返回	含义	该怎么做
INVALID_PARAMETER 等	参数有误，没执行	改参数重来
REVIT_BUSY	Revit 正忙，还没开始	可以直接重试
TIMEOUT	已经开始执行，结果不确定	用 operationId 调 revit_get_operation_status 查状态，不要直接重建

写工具还支持幂等键 requestKey：同一个键、同样的参数只会真正执行一次，超时后原样重发，拿回的是上次的结果，而不是再建一遍。

5. 建模指引随服务一起发布

实测中最费时间的问题，都不是“调用报错”，而是调用成功、警告为 0、几何是错的。为此项目整理了一份给智能体看的建模指引，其中有八条硬规则，例如：

• 先建一个代表实例，量准了再批量：第一次用某个族类型，先建一个，用 revit_get_element_geometry 量回来，对了再建剩下的几十个。
• 按实际几何验收，不看“成功”：一圈墙的合并包围盒应等于图纸外轮廓；大了一个墙厚，说明定位线方向反了。房间面积为 0 说明没围合。
• 区分“省略”和“明确给 0”：想让构件正好贴在标高上，就显式写偏移为 0，别靠省略碰运气。

这份指引编译在插件 DLL 里，通过工具 revit_get_modeling_guide、MCP 资源和服务开场白三条路发出去，客户端什么都不用装，而且永远和工具的实际行为是同一个版本。

6. 工具集分组，按需省上下文

75 个工具的说明加起来约 65 KB，每次会话都要占用智能体的上下文。RevitMCP 给每个工具标注了所属集合（核心 / 建筑 / 结构 / MEP / 出图 / 协同 / 编著 / 逃生舱），配置 enabledToolsets 只开用得上的：

场景	实测节省
纯查询	72.9%
只建模	59.7%
只出图	46.3%
建模 + 出图	33.2%

为什么不干脆只留一个“万能入口”工具，靠参数派发？因为那样每个工具的参数校验、“只读 / 破坏性”标注都会失效——客户端再也没法对删除操作单独弹确认，省下的那点上下文，会以更多的失败调用还回去。

五、安全：钥匙在人手里

• 默认只读：功能区上的操作模式默认是「浏览模型」，所有写工具直接被拒；只有用户手动切到「修改模型」，AI 才能改模型。这个开关 AI 自己打不开。
• 只改活动文档：写操作只作用于用户当前在看的文档，并支持 expectedDocumentId 前置校验——防止用户切了窗口，AI 却把一整层楼建进了别的模型。
• 逃生舱默认关闭：revit_invoke_api（反射调用任意 API）和 revit_execute_script（执行 C# 代码）绕开了所有保护，需要在配置文件里单独开启并重启 Revit，开着时功能区按钮会一直显示警示色。
• 导出路径受限：导出图片只接受文件名，一律落在固定的导出目录，防止 AI 被坏数据误导而覆盖用户的文件。
• 不替用户乱点对话框：认不出来的弹窗不会被自动点“确定”。
• 审计日志：每次调用记一行，成功、失败、被拒都记，入参只记摘要，回答“模型到底被动过什么”。
• 只在本机：服务只监听 127.0.0.1，需要访问令牌，并校验来源。

六、用企业标准自动复核模型

手里有一份院里的建模标准，能不能让它自动复核模型？RevitMCP 给出的做法是：把标准写成两份文件——一份给人看的条款（Markdown），一份给机器跑的规则（JSON），条款编号一一对应。

# 复核当前模型
powershell -File workflows/m9-audit.ps1 -Standard workflows/standards/示例企业建模标准.json

# 把 Revit 里打开的所有模型都过一遍，汇总“哪条规则最常被违反”
powershell -File workflows/m9-batch.ps1 -Standard workflows/standards/示例企业建模标准.json

几条从实践里得来的原则：

• 规则是数据，不是代码：JSON 可以进版本库，能对比、能审阅、能按项目分支。
• 违规必须点名到构件 ID：一句“命名不规范”没人能据此动手。
• 验不了的条款要写明为什么：比如“需在警告说明表中备案”涉及模型之外的文档，不能假装能验。
• 标准要在自己的模型上校准：示例里“每个建筑标高都必须有楼层平面”这条，在官方样例模型上一跑，基础、天花、屋顶线几个标高全被判违规——它们本来就不出平面图。

七、上手步骤

1. 构建并安装（不需要本机装 Revit 也能构建；安装前请先关闭 Revit）：

powershell -ExecutionPolicy Bypass -File build/build-all.ps1 -RevitYears 2024
powershell -ExecutionPolicy Bypass -File build/install.ps1 -RevitYear 2024

2. 启动 Revit，功能区出现 RevitMCP 选项卡。端口和令牌在面板的「接入信息」里。

3. 接入客户端。Claude Code 一行命令：

claude mcp add --transport http revit http://127.0.0.1:7801/mcp --header "Authorization: Bearer <token>"

Claude Desktop、Cline 等读 mcpServers 配置的客户端，把「接入信息 → JSON 配置」复制过去：

{
  "mcpServers": {
    "revit": {
      "type": "http",
      "url": "http://127.0.0.1:7801/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

4. 需要 AI 改模型时，在功能区把操作模式切到「修改模型」。只查询的话保持默认即可。

八、局限与路线图

• 暂不支持 Revit 2025 及以上版本。
• 原生楼梯和栏杆还没有专门的工具，目前只能靠逃生舱绕行。
• 材质能赋给构件，但墙的层构造还不能改（这是最先要补的一项）。
• 能载入和放置族、复制族类型，但不做“造族”——族文档是另一套 API 语义。
• 防止串文档的 expectedDocumentId 机制已有单元测试，还缺一轮“同时开两个模型、中途切换”的真实环境验收。

总结

让智能体操作 Revit，难的不是“调通 API”，而是调用成功、模型却不对。RevitMCP 的做法是把这些坑挡在工具里：一次调用一步撤销、失败必回滚、警告必上报、删除先演练、超时可查询，再配上一份随服务发布的建模指引，教智能体“按实际几何验收”。钥匙始终在人手里——默认只读，改不改模型由你决定。

如果你正在尝试让 AI 帮忙建模、出图或审模型，欢迎试用，也欢迎在 GitHub 上提 issue：https://github.com/CHMOSE023/RevitMCP