# RevitMCP：让智能体进入 Revit 建模 RevitMCP 是一个 Revit 插件，把当前打开的 Revit 模型通过 MCP 协议开放给 AI 智能体：查模型、建墙板门窗、出图导出、按企业标准复核，一个调用就是撤销栈里的一步，失败必回滚。 > 原文：[RevitMCP：让智能体进入 Revit 建模](https://qmbim.com/articles/bf1e0db0-9965-4301-a6ba-2aa3cae947cc) > 作者：迈智数创 · 发布于 2026-09-29 > 转载请注明出处并保留原文链接。 --- 项目地址： ## 一、它是什么 在《智能体（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 每个阶段的验收标准都不是“工具清单打勾”，而是**一条能跑通的真实工作流**。下面是其中一条的过程： ```text 目标：建一圈外墙围出一个房间 思考：先查标高和墙类型，挑一个 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），条款编号一一对应。 ```bash # 复核当前模型 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）： ```bash 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 一行命令： ```bash claude mcp add --transport http revit http://127.0.0.1:7801/mcp --header "Authorization: Bearer " ``` Claude Desktop、Cline 等读 `mcpServers` 配置的客户端，把「接入信息 → JSON 配置」复制过去： ```json { "mcpServers": { "revit": { "type": "http", "url": "http://127.0.0.1:7801/mcp", "headers": { "Authorization": "Bearer " } } } } ``` **4. 需要 AI 改模型时**，在功能区把操作模式切到「修改模型」。只查询的话保持默认即可。 ## 八、局限与路线图 - 暂不支持 Revit 2025 及以上版本。 - 原生楼梯和栏杆还没有专门的工具，目前只能靠逃生舱绕行。 - 材质能赋给构件，但墙的层构造还不能改（这是最先要补的一项）。 - 能载入和放置族、复制族类型，但不做“造族”——族文档是另一套 API 语义。 - 防止串文档的 `expectedDocumentId` 机制已有单元测试，还缺一轮“同时开两个模型、中途切换”的真实环境验收。 ## 总结 让智能体操作 Revit，难的不是“调通 API”，而是**调用成功、模型却不对**。RevitMCP 的做法是把这些坑挡在工具里：一次调用一步撤销、失败必回滚、警告必上报、删除先演练、超时可查询，再配上一份随服务发布的建模指引，教智能体“按实际几何验收”。钥匙始终在人手里——默认只读，改不改模型由你决定。 如果你正在尝试让 AI 帮忙建模、出图或审模型，欢迎试用，也欢迎在 GitHub 上提 issue：