Autodesk Revit Mcp Server

状态：位于 dev 分支，尚未发布。

AEC Model Bridge 是一款开源 Revit MCP 服务，可让 Claude、Codex、 Cursor 和其他 AI 助手读取和编辑当前打开的 Revit 模型。默认情况下， 你需要先批准每项更改。它由两部分组成：Python MCP 服务和原生 Revit 加载项。 只读工具可立即检查模型。默认情况下，模型变更需要经过批准的计划。 查看审批流程。

适用对象。 希望 AI 助手检查模型质量、查找受影响的构件并准备参数修复方案的 BIM 协调员和经理，同时由人员掌控每项更改。你无需编写脚本。

状态和限制。 这是预发布软件。

• 该产品尚未在实际 Revit 会话中经过验证。Python 服务已使用模拟提供程序进行测试，CI 会为 Revit 2024 到 2027 编译加载项，但不会启动 Revit。在有人检查之前，请将此处描述的所有 Revit 行为视为未验证。待办清单见发布检查清单。
• 本页面介绍的是 dev 分支。最新的 GitHub 版本可能不包含此处描述的所有内容。
• 请先在项目副本上试用。批准计划会更改当前打开的模型。
• 已知的一些限制列于审批工作原理和docs/security.md。
• dev 分支注册了更多工具（撰写本文时，模拟模式下有 241 个；请参阅 dev 分支）。

Star 历史记录

文档提供了 Claude Desktop、搭配 GitHub Copilot 的 VS Code、Cursor 和 Codex 的设置说明。该服务是标准的 MCP stdio 服务，因此 Claude Code、 Windsurf、Cline、Continue、Zed 和 Gemini CLI 等其他客户端也应该可以使用。本项目的 兼容性页面列出了已有文档说明的功能和未经测试的功能。

同一服务还可以检查 IFC 文件、自动化操作 Rhino 和 Grasshopper，并连接到 Speckle。集成状态会展示当前可用的提供方以及仍在开发中的提供方。

示例工作流

适用于 BIM 协调员：检查模型质量、查看受影响的元素、批准参数修复，然后检查结果并导出报告。这些示例使用 当前工具目录中的工具。

工作流	请求示例	使用的工具
模型审查	“显示当前活动文档，列出其中的警告并查找受影响的元素。”	revit_get_document_info、revit_get_warnings、revit_get_elements_by_type
参数更新	“查找 Level 02 上的墙，显示其 Comments 值，并提出批量更新方案。”	revit_get_elements_by_type、revit_get_element_parameters、revit_batch_set_parameters
图纸制作	“根据此 CSV 准备图纸列表，然后提出创建图纸并放置视图的方案。”	revit_batch_create_sheets_from_csv、revit_place_viewport_on_sheet
IFC 审查	“显示此 IFC 文件的楼层，检查墙的属性，并报告架构验证问题。”	ifc_get_spatial_structure、ifc_get_properties、ifc_validate

首次在 Revit 中运行时，可以试试：

Read the active model's warnings. Group them by description and show the
affected element IDs. Then suggest which issues to investigate first.

然后试试修正参数，并将楼层和值替换为项目中的内容：

Find walls on Level 02 and show their current Comments values. Propose setting
Comments to "Coordination reviewed" for the elements I choose. After I approve
the plan in Revit, apply it and read the values back to confirm the result.

对于编辑操作，助手会使用 plan_actions 创建计划。你可以在 Revit 面板中审核计划，之后才会由 execute_plan 应用更改。IFC 审查无需 Revit。

快照 QA/QC 和报告模块需要兼容的已保存快照。从 Revit 向这些模块传递数据时， 目前要求文件名和工作区匹配。如果省略 snapshot_id，大多数此类模块现在会在桥接 模式下明确提示并拒绝执行，而在模拟模式下仅返回生成的示例数据。并非每个模块都有此保护（model_bloat 没有），因此请务必传入 snapshot_id。如需实时检查，请使用上面的 Revit 直接工具。 计划修复和演示。

快速开始

60 秒内，无需 Revit（模拟模式）

1. 安装 uv。
2. 使用“手动设置”下方的 JSON 将服务添加到客户端，并设置 "MCP_REVIT_MODE": "mock"。下方的一键安装按钮会以 bridge 模式启动，该模式需要 Revit。
3. 重启客户端，并让它列出 AEC Model Bridge 工具。
4. 让它读取当前文档。模拟模式会返回生成的示例数据，绝不会读取你的模型，因此你可以通过回答了解这些工具和审批流程，再连接 Revit。
5. 要使用自己的模型，请安装 Revit 插件 （安装步骤），并将模式切换为 bridge。

一键安装

这些按钮需要 uv，除此之外无需其他依赖。除非自行设置工作区，否则服务会使用 ~/Documents/AEC Model Bridge。对于 Claude Desktop，请从最新发布版本下载 .mcpb 文件并打开。要实时操作 Revit，仍需安装 Revit 和 插件。模拟模式则两者都不需要。

手动设置

要实时自动化操作 Revit，你需要 Windows、正版 Revit 2024 至 2027、Python 3.11 或更高版本、uv，以及 Revit 插件 （安装步骤）。然后将以下内容添加到 claude_desktop_config.json（Codex、Cursor 和 VS Code 使用相同的值； 两个目录变量为可选项，默认使用上述工作区）：

{
  "mcpServers": {
    "aec-model-bridge": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Sam-AEC/aec-model-bridge#subdirectory=packages/mcp-server-revit",
        "aec-model-bridge"
      ],
      "env": {
        "MCP_REVIT_MODE": "bridge",
        "MCP_REVIT_WORKSPACE_DIR": "C:\\RevitProjects",
        "MCP_REVIT_ALLOWED_DIRECTORIES": "C:\\RevitProjects"
      }
    }
  }
}

想先了解这些工具，但暂时不使用 Revit？请设置 "MCP_REVIT_MODE": "mock"。 此时服务可在任何机器上启动，列出所有工具及其架构，并返回预设响应。它不会触碰任何模型。仓库根目录中提供了用于相同模拟模式的 Dockerfile（docker build -t aec-model-bridge .，然后运行 docker run -i --rm aec-model-bridge）。

使用 VS Code？扩展源代码和本地安装步骤 会注册 MCP 服务并显示 Revit 连接状态。该扩展尚未发布到 Marketplace。

工具一览

类别	工具	功能
Revit	103	读取模型，创建和编辑图元、参数、视图、图纸、明细表、导出内容，以及工作共享
审批	6	规划、审查、批准、执行和回滚模型更改
模块	34	快照检查、参数网格、QA/QC 检查、配方、报告、选择集
Rhino 和 Grasshopper	19	几何体、图层、材质、布尔运算
Speckle	17	项目、模型、版本、发送和接收
Navisworks	15	模型树、视点、碰撞测试（进行中）
IFC	7	无需 Revit 即可读取 IFC 文件：结构、属性、验证
图、快照、导出、任务	18	语义图审计、快照差异、SQLite 导出、后台任务

默认设置中列出了 219 个工具（根据当前服务器在模拟模式下统计）。配置 APS 凭据后会显示 Autodesk Data 工具。工具参考列出了所有工具。每个工具都带有 MCP 注解（readOnlyHint、destructiveHint、idempotentHint、 openWorldHint），因此客户端可以区分读取和写入操作。

高级 Revit 自动化

除了模型查询和参数更新外，Revit 工具还可以创建建筑构件、视图、图纸、明细表、标记和尺寸标注，并导出 IFC、DWG、图像和 Navisworks 文件。有关支持的操作和输入，请参阅工具参考。

对于工具目录未涵盖的内容，revit_invoke_method、revit_reflect_get 和 revit_reflect_set 可用于操作 Revit API 的公共成员。revit_execute_python 可在 Revit 内运行 IronPython。这些高级工具拥有与 Revit 进程相同的权限。仅在使用你信任的 MCP 客户端和提示词时使用它们。

工作原理

MCP 客户端与一个 Python hub 通信。hub 会将每次调用发送给拥有该工具的提供方。桌面应用的提供方通过 localhost 与应用内的小型插件通信。

_{图表源文件：architecture.mmd。使用 python scripts/render_diagrams.py 重新生成图像。}

青绿色框表示目前可用。琥珀色虚线框表示正在开发。靛蓝色形状表示数据和外部服务。

审批机制

简单来说：

• 有两种模式可供使用。 look_only 允许助手读取，但会拒绝所有会更改模型的工具。ask_first（默认模式，也写作 required）允许它起草更改，但必须经由人员审批后才会执行。第三个值 auto 会关闭检查，仅适用于受控管线。
• 只有人员可以审批。 不会向 AI 客户端提供审批、拒绝和回滚计划的功能。人员可在 Revit 面板中审批，也可使用 aec-model-bridge-approve 命令。
• 所有更改都不会自行应用。 只有当某项更改与某个已批准计划中的已批准操作相匹配时，才会执行一次。
• 撤销按操作逐项进行。 每按一次 Ctrl+Z，Revit 就撤销一个操作。

除非工具调用附带已批准的计划，否则 hub 会阻止所有会更改模型的工具调用。AI 会提出计划，由你审核，再由加载项在 Revit 主线程上执行。面板的 Plans 列表会显示每个待处理计划中的工具、参数，以及（如果已捕获）更改前的值。若要完整查看计划，包括助手附带的任何推理和警告，请运行 aec-model-bridge-approve show <plan_id>；面板不会显示这些审核文本。参数和模型编辑操作各自在独立的命名事务中执行；部分操作（保存、同步、脚本）不使用事务，因此无法通过 Ctrl+Z 撤销。

_{图表源文件：approval-flow.mmd。运行 python scripts/render_diagrams.py 重新生成图片。}

如果发现计划有误，可使用 Revit 的 Ctrl+Z 撤销。每次参数写入都在独立的命名事务中执行，因此撤销一个计划可能需要按多次。目前尚未实现整份计划一步撤销，但已有此计划。另一种方法是创建还原计划：助手根据已执行计划的执行凭证，使用 plan_revert 起草还原计划，然后你像审批其他计划一样审批。rollback_plan 也会按相反顺序写回记录的更改前的值；如果某项操作没有记录更改前的值，则可以跳过该操作。不过此功能仅供人员使用，尚无面板按钮或命令行命令，因此请勿依赖它。目前这些方法均未在实时 Revit 会话中验证（UNVERIFIED）。文件输出等无法撤销的操作不会通过上述任何方法撤销，目前也尚未提供二次确认（计划中）。面板的 Plans 列表只显示待处理计划；aec-model-bridge-approve show <plan_id> 适用于任何状态的计划，而 proofs/ 目录中的执行凭证包仅适用于已执行（或尝试执行）的计划。生命周期说明见 ADR 0008。

对于无人值守的管线，可设置 MCP_REVIT_APPROVAL_MODE=auto。这会关闭人员检查，因此仅应在受控环境中使用。

支持的 Revit 版本

Revit 版本	加载项目标	构建工具
2024	.NET Framework 4.8	.NET 8 SDK 和 .NET Framework 4.8 开发人员包
2025	.NET 8 for Windows	.NET 8 SDK
2026	.NET 8 for Windows	.NET 8 SDK
2027	.NET 10 for Windows	.NET 10 SDK

这些是构建目标。CI 会为这四个年份编译加载项，但目前还没有在实时 Revit 会话中验证任何年份。

你还需要 Windows 10 或 11、Python 3.11 或更高版本，以及所用版本的正版 Revit 安装。模拟模式无需 Revit 即可运行服务，适用于开发和测试。

其他集成

集成	状态
Revit	可用。原生 C# 加载项。
IFC (IfcOpenShell)	可用。无需运行 Revit 即可读取 IFC 文件。
Rhino 和 Grasshopper	可用。连接到 localhost:3004 上的 Rhino 加载项。
Speckle	可用。需要在环境中设置 Speckle 客户端 ID。
Navisworks Manage	开发中。已注册提供方及其工具。Navisworks 加载项尚未完成。
Power BI	开发中。提供方和工具已存在，但尚未在中心注册。
Excel、Parquet 和 DuckDB	计划中。

产品名称和徽标归其所有者所有。横幅仅用它们来展示本项目支持的产品。

安装 Revit 加载项

最简单的方式（Windows）： 从最新版本下载 AECModelBridge-Setup-<version>.exe，双击运行，选择 Revit 版本并重启 Revit。安装程序会安装加载项和附带的 Python 服务。如果勾选相应选项，它还会配置 Claude Desktop 和 VS Code，并在此之前备份你当前的设置。可在 Windows 设置中卸载。以下步骤适用于从源代码构建。

你需要安装两个部分：Python MCP 服务和 Revit 加载项。实时 Revit 自动化需要两者都已安装。

1. 安装 MCP 服务

git clone https://github.com/Sam-AEC/aec-model-bridge.git
cd aec-model-bridge

py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e packages/mcp-server-revit

2. 安装 Revit 加载项

将版本设置为与你安装的 Revit 版本一致。如果 Windows 阻止下载的脚本，请右键单击每个 .ps1 文件，打开属性，然后在运行前选择“解除锁定”。

$RevitVersion = Read-Host "Revit year (2024, 2025, 2026, or 2027)"

.\scripts\package.ps1 -RevitVersion $RevitVersion
.\scripts\install.ps1 -RevitVersion $RevitVersion

安装程序会将对应版本的二进制文件放在：

C:\ProgramData\AECModelBridge\bin\<year>

加载项清单会按用户安装在：

%APPDATA%\Autodesk\Revit\Addins\<year>

使用 install.ps1 搭配 -AllUsers，可将清单安装到 C:\ProgramData\Autodesk\Revit\Addins\<year>。

一次性为所有支持的版本准备二进制文件：

.\scripts\package.ps1 -RevitVersion All

每个 GitHub 版本 都提供适用于对应 Revit 年份的预构建包，例如 aec-model-bridge-revit-2026-<version>.zip。解压后运行 .\install.ps1 -RevitVersion 2026，无需从源代码构建。如需双击即可运行的 Windows 安装程序，可使用 Inno Setup 通过 scripts/build-installer.ps1 构建。 包含故障排除内容的完整指南见 docs/install.md。

将 Claude Desktop 连接到 Revit

将服务器添加到 MCP 客户端配置中。对于 Claude Desktop，这是 claude_desktop_config.json 中的 mcpServers 部分。Codex、Cursor、VS Code 和其他 MCP 客户端在各自的配置格式中使用相同的 command、args 和 env 值。

使用虚拟环境中的 Python 可执行文件，并选择一个服务器可以访问的工作区文件夹：

{
  "mcpServers": {
    "aec-model-bridge": {
      "command": "C:\\path\\to\\aec-model-bridge\\.venv\\Scripts\\python.exe",
      "args": ["-m", "revit_mcp_server.mcp_server"],
      "env": {
        "MCP_REVIT_MODE": "bridge",
        "MCP_REVIT_WORKSPACE_DIR": "C:\\RevitProjects",
        "MCP_REVIT_ALLOWED_DIRECTORIES": "C:\\RevitProjects"
      }
    },
    "aec-model-bridge-revit-2026": {
      "command": "C:\\path\\to\\aec-model-bridge\\.venv\\Scripts\\python.exe",
      "args": ["-m", "revit_mcp_server.mcp_server"],
      "env": {
        "MCP_REVIT_MODE": "bridge",
        "MCP_REVIT_HOST_VERSION": "2026",
        "MCP_REVIT_WORKSPACE_DIR": "C:\\RevitProjects",
        "MCP_REVIT_ALLOWED_DIRECTORIES": "C:\\RevitProjects"
      }
    }
  }
}

省略 MCP_REVIT_HOST_VERSION，即可连接到最新打开的 Revit 实例。将其设为 2024 或 2026 之类的年份，可将客户端配置项锁定到该 Revit 版本。MCP_REVIT_BRIDGE_URL 可覆盖端点，供高级设置使用。

VS Code 用户可以从 .vscode/mcp.json 开始配置。Hermes Desktop 用户可以从 docs/examples/hermes-desktop.json 开始配置，并替换其中的 Python 路径占位符。支持 MCP Bundles 的客户端可以从最新版本安装 .mcpb 文件。仍然需要 Revit 插件，因为服务器要与正在运行的桌面应用程序通信。

检查连接

安装插件后重启 Revit，打开一个模型，然后运行：

$registry = Get-ChildItem "$env:LOCALAPPDATA\AECModelBridge\registry\revit-*.json" | Select-Object -First 1
$switch = Get-Content $registry.FullName -Raw | ConvertFrom-Json
Invoke-RestMethod "$($switch.endpoint)/health"

响应应显示 healthy 和正在运行的 Revit 版本。在 Revit 中，查找 AEC Bridge 功能区选项卡。其 Workflows 面板包含 Open Panel、Health Check、Pending Actions 和 Reports。其 Tools 面板包含 Config、Help 和 About。

安全

• Revit 桥接仅监听 localhost。
• 服务器只会在 MCP_REVIT_ALLOWED_DIRECTORIES 中列出的文件夹内读取和写入文件。
• 修改模型的工具需要经过批准的计划，除非你关闭审批；look_only 模式则会直接拒绝这些工具。
• 审批记录会注明渠道（面板或命令行）以及你的操作系统账户。它不能证明是谁在输入，因此不要让 AI 客户端在你用来批准计划的账户下访问 shell。
• 工具调用会写入审计日志，并会对密钥进行脱敏。

详情请参阅 docs/security.md。如需报告漏洞，请遵循 SECURITY.md。

常见问题

什么是 Revit MCP 服务？

模型上下文协议（MCP）是一项开放标准，可让 AI 助手调用其他软件中的工具。Revit MCP 服务会将 Revit 操作发布为工具。助手选择工具，插件则在 Revit 中运行这些工具。

哪些 AI 助手可以与它配合使用？

任何能够启动本地 stdio 服务的 MCP 客户端都可以。文档提供了 Claude Desktop、搭配 GitHub Copilot 的 VS Code、Cursor 和 Codex 的配置说明，也适用于读取标准 mcpServers 配置的客户端。Windsurf、Cline、Roo Code、Continue、Zed、Claude Code 和 Gemini CLI 应该也能以相同方式运行，但尚未经过测试。请参阅兼容性。面板聊天也可以使用 Anthropic API 密钥，或使用已安装的 claude 或 codex 命令行工具。请参阅 ADR 0012。

AI 能否不经询问就更改我的模型？

在默认模式下不能。更改模型的工具会被阻止，直到有人在 Revit 面板中批准计划，或通过 aec-model-bridge-approve 命令批准计划。只读工具无需审批即可运行。在 look_only 模式下，任何会更改模型的操作都不会运行。如果设置 MCP_REVIT_APPROVAL_MODE=auto，则会跳过审批。

它会将我的模型发送到云端吗？

服务器和插件都在你的计算机上运行，桥接仅监听 localhost。AI 助手会看到工具返回的内容，而这些结果会发送给客户端背后的模型提供商。Speckle 等云服务提供商只有在你进行配置并调用其工具时才会运行。

不使用 Revit 也能处理 IFC 文件吗？

可以。IFC 提供程序使用 IfcOpenShell 读取文件。它可以返回文件元数据、空间结构、元素属性和边界框，按类别、GUID、名称或属性运行查询，并验证架构。它不会编辑 IFC 文件。

不安装 Revit 可以使用吗？

只能在模拟模式下使用，该模式用于开发和测试。要操作实际模型， 需要 Revit 2024 至 2027 以及加载项。

发布和版本

AEC Model Bridge 遵循语义化版本规范。发布版本会在 GitHub 上标记为 vX.Y.Z， 根目录中的 VERSION 文件记录版本号。有关发布流程，请参阅 docs/versioning.md；有关各版本的变更，请参阅 CHANGELOG.md。

开发

# Python tests
python -m pytest packages/mcp-server-revit/tests

# Build one Revit version, for example 2026
.\scripts\build-addin.ps1 -RevitVersion 2026 -Configuration Release

# Build all supported versions
.\scripts\package.ps1 -RevitVersion All

CI 会构建 Python 服务端以及适用于 Revit 2024 至 2027 的加载项目标。 提交拉取请求前，请参阅 CONTRIBUTING.md。

文档

• 安装指南
• 工具参考
• 架构
• 配置参考
• 安全性
• MCP 客户端和注册表
• 版本管理和发布
• 发布检查清单
• 安装后的首次检查
• 演示运行手册
• 证明包和还原计划
• 隐私
• 路线图
• 所有文档
• 贡献指南和行为准则
• 贡献者

构建所用技术

AEC Model Bridge 基于开源项目构建。它是独立项目，与此处提及的任何项目均无关联，也未获得其认可。

• 用于 MCP 服务的 Model Context Protocol Python SDK（MIT）
• 用于 IFC 文件的 IfcOpenShell（LGPL-3.0-or-later）
• 用于 Speckle 的 specklepy（Apache-2.0）
• pydantic、httpx、NetworkX、openpyxl 和 PyYAML（MIT 或 BSD）
• 用于内置 Agent 聊天功能的 Anthropic Python SDK（MIT）
• Revit 加载项中的 Serilog、IronPython 和 Microsoft WebView2
• Autodesk Revit 和 Navisworks 以及 McNeel Rhino 是需要自行取得许可的独立产品。本项目不包含其代码。

许可证文本和完整的软件包列表见 THIRD_PARTY_NOTICES.md。许可证信息取自软件包元数据；无法核实的条目均已注明。

项目和许可证

由 A. Sam Mohammad 维护。 LinkedIn | 问题反馈

GPL-3.0-or-later（附 Revit 链接例外），或商业许可证。