RvtMcp

rvt-mcp

Autodesk Revit 的 MCP 网关 — 为 Agent 提供本地工具，可选的个人工具构建循环

English · Tiếng Việt · 简体中文 · 日本語

项目简介

面向 Revit 的早期全 C# MCP 实现 — 自 2026 年 3 月起开展研究与实现。

rvt-mcp 是 MCP 客户端与正在运行的 Revit 会话之间的本地桥接。基于 .NET 8 的服务通过 stdio 使用 MCP 通信；每个 Revit 年份版本（2022–2027）都有一个轻量加载项，在 Revit 内运行，并通过 localhost TCP（≤2024）或命名管道（≥2025）访问。所有数据都留在本机，端到端均使用 C#，工具边界处的长度单位为毫米。详情请见：ARCHITECTURE.md。

Agent 可使用用于常见 Revit 操作的类型化工具接口、用于处理其他需求的 C# 扩展入口，以及将重复模式转化为个人工具的可选方式（ToolBaker）：从共享运行时开始，在其基础上逐步构建自己的工具。目前不支持在族编辑器中创作内容。

安装

v1.2.0： 安装说明和 Claude Desktop MCPB · NuGet（仅服务端） · MCP Registry。请参阅验证记录和剩余覆盖范围。

让 AI Agent 为你的目标客户端安装。 使用能够运行 PowerShell 并编辑这台 Windows 计算机上的本地文件的 Agent（Claude Code、Codex、Cursor 等），而不是无法使用本地工具的聊天会话。执行安装的 Agent 可以与要使用 Revit 工具的客户端不同。它会遵循 AGENTS.md，预览更改并在应用前征求确认；你可能仍需要批准某个 UI 操作或重启应用。

对于 Claude Desktop，请粘贴：

Install rvt-mcp for Claude Desktop on this Windows machine.
First read https://github.com/bimwright/rvt-mcp/blob/master/AGENTS.md.
Configure only Claude Desktop, not other clients. Inspect existing installations,
preview changes and ask before writing. Tell me if I need to use the UI or restart an app.

对于其他客户端，请将 Claude Desktop 替换为其名称。Claude Code 和 Claude Desktop 是不同的目标： 安装程序选项 claude 表示 Code；claude-desktop 表示 Desktop。

或者自行运行安装程序（Claude Desktop，直接配置）。 关闭 Revit 并完全退出 Claude Desktop（包括托盘进程），然后在 PowerShell 中运行：

$tag = (Invoke-RestMethod https://api.github.com/repos/bimwright/rvt-mcp/releases/latest).tag_name
$dir = "$env:TEMP\RvtMcp.Setup-$tag-win-x64"
Invoke-WebRequest "https://github.com/bimwright/rvt-mcp/releases/download/$tag/RvtMcp.Setup-$tag-win-x64.zip" -OutFile "$dir.zip"
Expand-Archive "$dir.zip" -DestinationPath $dir -Force
powershell -ExecutionPolicy Bypass -File "$dir\install.ps1" -WhatIf -Client claude-desktop
# Review the preview before applying:
powershell -ExecutionPolicy Bypass -File "$dir\install.ps1" -Client claude-desktop

这会为所有检测到的 Revit 2022–2027 安装加载项，并且仅在 Claude Desktop 中注册 rvt-mcp（会先备份配置）。对于 Claude Code，请使用 -Client claude；对于多个指定客户端，请使用逗号分隔的列表。省略 -Client 会为所有检测到的客户端配置连接；-Client none 则不会更改配置。服务端位于 %LOCALAPPDATA%\Bimwright\rvt-mcp\server\current\rvt-mcp.exe（各客户端的配置步骤，包括 Desktop classic/MSIX 路径）。

检查是否正常运行： 重启 AI 客户端，在 Revit 中打开一个模型，从功能区启动 MCP（Add-Ins → RvtMcp），然后让 Agent 调用 revit_get_current_view_info。它应返回活动视图的名称和类型。

升级： 关闭 Revit 和网关客户端，备份产品数据文件夹，然后直接运行新版安装程序，无需先卸载。设置和 ToolBaker 数据会保留。MCPB 用户请使用 -Client none，从同一版本更新 Setup 和扩展，然后在重新连接前检查 Desktop 设置和权限。请参阅升级步骤。卸载： uninstall.ps1 -Yes 会移除加载项和服务端；除非添加 -Purge，否则会保留个人数据。若也要移除客户端条目，请先运行 install.ps1 -Uninstall -Client auto。

从 v0.8.1 或 v0.6.x 升级： 这些版本会将设置和 ToolBaker 数据保存在 %LOCALAPPDATA%\RvtMcp\；v1.0.0 使用 %LOCALAPPDATA%\Bimwright\rvt-mcp\，安装程序会将旧文件夹移至该位置。请先关闭 Revit 和所有 MCP 客户端，因为正在运行的旧服务端会锁定文件夹。在 PowerShell 中使用 Test-Path "$env:LOCALAPPDATA\RvtMcp" 检查。如果安装程序因 Both … exist 或 Could not move … 而停止，它已撤销移动操作：保留包含设置和 ToolBaker 数据的文件夹，将另一个文件夹重命名（例如重命名为 RvtMcp.bak），而不要删除它，关闭正在使用该文件夹的客户端，然后重新运行安装程序。

Claude Desktop 扩展（MCPB，可选）： 对于由 Agent 辅助的安装，默认采用上文的直接配置。如果你想使用扩展/设置 UI，请使用 -Client none 运行 Setup，然后通过 Desktop 的扩展 UI 安装 .mcpb。选择一种方式，不要两种都用。 -Client none 不会移除已有的手动注册。请使用与 Setup 相同版本的发布包；它不会安装网关/加载项，并且需要该版本对应的精确服务端构建。请查看发布说明了解签名状态。请参阅 MCPB 安装和设置。

视频

社区成员分享的 rvt-mcp 实际使用视频。视频中展示的安装步骤可能早于本 README，请按上文的步骤操作。

• 将 ChatGPT Astra 连接到 Revit | 在真实项目中测试 AI 变更 — Revit Mentor
• 探索 Revit + GPT 6 Astra — BIM Pure
• GPT-6 Astra 仅用 14 分钟就建成了一栋 Revit 房屋 — Archi Vlogs

工具

以下数量与 v1.2.0 版本相符；后续开发版本可能会提供不同的工具目录。

统计不包括个人构建的工具。只有当 rvtmcp.config.json 尚未设置 toolsets 时，安装程序才会写入预设默认值——升级时会保留你自己的列表；移除该键（或设置你自己的 CSV）后，裸服务会恢复为包含 50 个工具的界面。只读筛选器会筛选出 ReadOnly=true 的单个工具，包括混合工具集中可读取的工具。即使工具的默认输出为内联形式，也会排除可写入文件的工具。

会话健康状态

会话开始时，如有需要，请选择目标 Revit 实例，然后调用 revit_health()。默认情况下，它保持离线状态，可与 --read-only 配合使用，也无需打开模型。revit_health(check_updates=true) 会明确将已加载的网关和插件与一个官方稳定版本进行比较；缺少的依据仍标记为 unknown。请遵循 update_guidance；只有当 prepare_update 的 bundle_update_proposal_allowed=true 时，才允许提出更新建议。健康检查不会安装更新、关闭模型或重启进程。即使 Revit 处于模态状态，它也可以回复。文档字段是最近一次 UI 观察的结果，时间由 document_observed_utc 标注，并不能确认当前文档或是否已准备好执行写入。重新连接后，请将最新的 initialize.serverInfo 以及 tools/list 中健康检查工具的运行时元数据、架构和注释与 client_verification 进行比较；服务端无法观察客户端缓存是否已刷新。

参数错误

调用缺少必需参数时不会运行。它会返回 INVALID_ARGUMENT 和 invalid_arguments（包含 missing、带有 did_you_mean 的 unknown、received、expected）。参数名称区分大小写，有些工具使用 snake_case，另一些使用 camelCase：请遵循 did_you_mean。键不是参数时，不会阻止调用。该键会被忽略，结果会在 _ignored_arguments 下列出该键。无法转换的值仍会返回 An error occurred invoking '<tool>'.，具体原因会显示在服务端的 stderr 中。

send_code、ToolBaker、功能区和语言

• revit_send_code_to_revit（默认开启）会在没有合适的类型化工具时，在 Revit 中编译并运行 C# 主体；使用 --read-only 或 --disable-send-code 会移除此工具。请参阅 docs/send-code.md，关于楼梯，请参阅 docs/stairs-workflow.md。
• ToolBaker：revit_list_baked_tools / revit_run_baked_tool 需要 --toolsets toolbaker。自适应烘焙（--enable-adaptive-bake，默认关闭）会根据重复调用推荐工具；在你接受之前，不会添加任何工具。烘焙会在 Revit 中编译，无需 Visual Studio。请参阅 docs/bake.md。
• **功能区：**启动或停止连接，打开 History 搜索过去的调用并查看 Issues，以及切换完成提示 Toasts（默认开启）。
• **UI 语言：**插件 UI 支持 15 种语言，并遵循 Revit 的 UI 语言；可通过功能区滑出面板中的 Language 按钮更改，它会打开 Settings → General → Language（BIMWRIGHT_UI_LANGUAGE 仍具有优先权）。工具名称和有效载荷保持英文。请参阅 docs/localization.md。

活动提示卡为何存在

提示卡用于反馈工作进展，而不仅仅是装饰。它们源于三项实际需求：

• 让用户不必一直盯着聊天窗口。 在真实的 MCP 工作流中，AI Agent 可能会长时间工作，而 Revit 几乎不会提供明显的反馈。为了确认 Agent 是否在工作而一直盯着聊天窗口，会浪费注意力。活动卡片会报告已完成的工具调用，让用户在两次更新之间处理其他工作。
• 支持多任务处理。 维护者会并行开发并反复测试多个桌面应用。紧凑的通知让用户更容易跟进这些会话，而不必始终打开每个聊天窗口。
• 让体验更现代。 Revit 端的反馈让自动化更及时、更易理解，同时不会用模态对话框打断工作。

提示卡报告的是工具结果，并非正在运行的工具内部的进度，也不代表整个任务已完成。连续的结果会合并到同一张卡片中；Revit 最小化或被模态对话框阻挡时，通知可能会暂缓显示。它们不能替代对 Agent 工作成果的检查。

每张卡片都会显示网关和 Revit 年份（例如 rvt-mcp 2022）、最新工具，以及 Success · Failed · Capture 计数。捕获预览会至少在卡片上显示 5 秒。

将鼠标有意悬停在卡片上，会打开活动时间线，显示最新的三个结果及各自的本地完成时间（HH:mm:ss）。向上滚动可查看该卡片中更早的调用。新结果到来时会跟随到底部，并以短暂的滑入动画显示（行向上移动，新行淡入，结果圆点弹出；启用减少动态效果时则不会播放这些动画）；阅读较早的调用时，滚动位置会保持不变。点击时间线内部即可阅读内容而不关闭时间线；点击卡片其余区域则会打开 History。关闭品牌标识时也可使用此功能。摘要有长度限制并经过脱敏处理，仅保存在内存中，卡片关闭时即清除。脚本对象和数组会显示计数；未完成的调查会明确标记为未完成。此 UI 更改不会让服务端本地工具获得提示卡支持。

通知默认开启，也可以关闭。在 Settings → Toast 中选择空闲时长（10/20/30/60 秒；默认为 20 秒）和 Show branding（默认关闭），开启后会在悬停时显示品牌字标。设置会立即生效，并在 Revit 重启后保留；无需显示品牌标识即可获得活动反馈。

**位置：**在 Settings → Toast 中分别选择 Horizontal alignment（Left/Right）和 Vertical alignment（Top/Bottom）；默认位置为左上角。更改会应用于当前打开的卡片并立即保存；更改角落位置会清除已保存的拖动位置。开启 Allow dragging the card 后，可通过标题栏移动卡片；普通点击仍会打开 History。关闭拖动时会保留已保存的位置，重新开启后会恢复该位置；Reset position 会清除该位置。位置相对于 Revit 窗口保存，并限制在显示器的工作区域内。固定在底部的卡片会向上展开，空间不足时则会切换到另一侧。动画效果遵循 Windows 动画设置。保存失败时，设置项下方会显示提示，但当前选择在本次会话中仍然有效。将鼠标悬停在最新工具行或时间线行上时，会显示经过脱敏处理的结果、Success/Failed、完成时间，以及可用时显示测得的耗时。此功能不负责协调多个 Autodesk 应用的提示卡。

提示词

v1.0.0 提供六个 MCP 提示词 — 选择 /mcp__rvt-mcp__revit_<name>（Claude Code），或打开提示词菜单（Claude Desktop），Agent 会使用现有工具遵循脚本：

• revit_getting_started — 熟悉打开的模型（只读，使用默认设置即可）。
• revit_drawing_layout — 提供 request：排列一张图纸上的视口。先读取真实的图纸空间位置（revit_get_viewport_geometry），与您确认对齐方式，显示试运行方案（revit_align_viewports），仅在您确认后移动，然后读取结果。需要 query,sheets,view,meta。在只读模式下仅报告并提出建议。
• revit_change — 提供 change：调查关联关系，就此请求所需的最小范围达成一致，在写入前确认具体方案，然后读取结果并在对话中记录原因。需要 query,meta；无需 send_code。在只读模式下会在调查和提议阶段停止。缺失或不完整的证据仍标记为“未检查”；读取结果并非间接变更的完整清单，记录也不是持久化的变更数据库。
• revit_model_audit — 健康审计：警告、族、清理候选项试运行（需要 workflows,families,lint,meta）。
• revit_pre_issue_check — 发布前检查已解析的图纸（需要 sheets,view,annotation,lint,meta）。提供图纸编号/ID、明确的编号/名称筛选条件，或 all；如果指定了图纸集，则需要提供其中的图纸。抽样模型警告和未完成的检查会报告为 NOT VERIFIED，而非图纸级别的通过。
• revit_stairs — 通过 send_code 引导创建楼梯（仅在您确认后写入）。包含事务/失败/清理模板；无需检出源代码。

如果未启用提示词所需的工具集，它会给出需要添加的准确 --toolsets 行 — 不会以半配置状态运行。缺少的工具允许时，仍会启用只读保护；需要具备写入能力的工具集的提示词会说明冲突，而不会悄悄更改配置。提示词是给 Agent 的指令，不是由服务端强制执行的工作流锁。

配置

v1.2.1 源码（发布准备）： 历史问题不再阻止后续写入或相同请求。当前事务警告仍默认触发回滚；可在 设置 → 常规 → 安全、JSON、环境变量或 CLI 中显式选择 accept-and-log 警告策略。错误、损坏、捕获不完整和当前持久化失败仍需要回滚。在 历史记录 → 问题 中查看记录；即使 Revit 处于模态状态，revit_get_failure_records 和 revit_get_operation_status 也能读取本地状态。决定下一步操作前，请检查待处理/未知结果。请参阅受控失败和接受限制。

从 v1.0.0 起，服务端会报告 _changes 和本地的每模型 _history。历史记录默认独立于调用日志启用；使用 --disable-change-history 可禁用记录。meta 工具 revit_record_change、revit_get_change_records 和 revit_resolve_history_identity 可为明确的调用 ID 添加原因、查询存储的变更，并在复制或使用 Save As 后记录所有者对历史记录的选择。有关隐私、限制和恢复，请参阅变更跟踪。

revit_survey_change_impact 是 query 中的工具：对十组关联关系进行有界只读调查，即使禁用了 send-code 也可使用。每个请求都必须提供 scopeThreshold；视图/明细表迭代需通过 maxViews > 0 显式启用。部分结果会明确标示，参数观察结果不会被视为可信的历史快照。请参阅变更影响调查。

优先级从高到低：CLI → 环境变量（BIMWRIGHT_*）→ %LOCALAPPDATA%\Bimwright\rvt-mcp\rvtmcp.config.json。

设置中的警告策略更改使用 应用 / 放弃，并会在下一次 MCP 调用时生效，不会重试先前的调用。只有客户端明确设置的 CLI/环境策略会覆盖主机按调用配置的策略；网关的启动 JSON 不会锁定已保存的设置值。Revit 进程的环境变量覆盖项会显示在设置中，并禁用该行。请参阅警告策略的限制和记录。

设置中的日志保留期限选项恰好为 1h、4h、8h、12h、24h、2d、7d、14d。已保存的 persistSendCodeBodiesHours 仍为整数小时数（1-336）；默认值仍为 4h。延长保留期限会明确延长日志内容的保留时间；但这本身不会启用日志记录。

更改服务标志后，请重启 MCP 连接，以便客户端获取新的工具列表。 在同一配置文件中，MCP 功能区切换开关会将最近一次成功的开启／关闭状态保存为 autoStartTransport。Revit 会在下次启动时使用该值；关闭 Revit 或以编程方式停止传输不会覆盖该值。同一 Windows 用户的不同 Revit 版本和实例共用此文件，因此最近保存的切换状态决定后续实例的启动状态，但不会更改已在运行的实例。未设置该值时，默认为开启。在 Revit 进程环境中设置 BIMWRIGHT_AUTO_START_TRANSPORT 后，它会在启动时覆盖已保存的值；功能区仍会保存用户的选择，但后续启动时环境变量的覆盖仍然生效。保存失败时会显示提示，切换开关仅对当前会话生效。

如果检测到该 Revit 版本中存在其他第三方 MCP 加载项，rvt-mcp 将以关闭状态启动，即使已保存的状态或环境变量要求开启也是如此。Autodesk 官方 Revit MCP 不受此限制。此启动覆盖不会更改已保存的偏好设置。点击功能区切换开关手动启动时，会显示本地化的模态提示，其中包含第三方 MCP 加载项的数量（包括 rvt-mcp）；确认后即可启动。检测会读取 .addin 清单和兼容的 bundle 注册信息，识别 MCP 名称、类名和程序集名称，并对重复注册进行去重。隐藏在通用加载器元数据后的 MCP 实现可能无法识别。

权限与自动模式

这些控制项将在 v1.0.0 中推出。v0.8.1 软件包不包含这些新开关或按工具进行的只读过滤。必须直接调用 send_code 和 run_baked_tool；batch_execute 会拒绝它们。

MCP 注释会说明每个工具对文档/文件的影响。临时选择、活动视图和缩放更改均视为只读。send_code 没有注释：不要将它纳入自动权限，并且每次调用任意代码时都要确认。对于 Claude Code，只复制下面的只读允许列表；不要允许宽泛的 mcp__rvt-mcp__* 通配符。该列表涵盖 --toolsets all；你选择的工具集可能只公开更少的工具。

{
  "permissions": {
    "allow": [
      "mcp__rvt-mcp__revit_activate_view",
      "mcp__rvt-mcp__revit_ai_element_filter",
      "mcp__rvt-mcp__revit_analyze_geometry_complexity",
      "mcp__rvt-mcp__revit_analyze_mep_network",
      "mcp__rvt-mcp__revit_analyze_model_statistics",
      "mcp__rvt-mcp__revit_analyze_sheet_layout",
      "mcp__rvt-mcp__revit_analyze_structural_connections",
      "mcp__rvt-mcp__revit_analyze_usage_patterns",
      "mcp__rvt-mcp__revit_analyze_view_naming_patterns",
      "mcp__rvt-mcp__revit_audit_families",
      "mcp__rvt-mcp__revit_clash_detection",
      "mcp__rvt-mcp__revit_compute_element_area",
      "mcp__rvt-mcp__revit_compute_element_volume",
      "mcp__rvt-mcp__revit_detect_firm_profile",
      "mcp__rvt-mcp__revit_detect_system_elements",
      "mcp__rvt-mcp__revit_find_elements_in_volume",
      "mcp__rvt-mcp__revit_find_mep_disconnects",
      "mcp__rvt-mcp__revit_find_overlapping_elements",
      "mcp__rvt-mcp__revit_find_schedule_elements",
      "mcp__rvt-mcp__revit_find_undimensioned_elements",
      "mcp__rvt-mcp__revit_find_untagged_elements",
      "mcp__rvt-mcp__revit_get_assembly_members",
      "mcp__rvt-mcp__revit_get_available_family_types",
      "mcp__rvt-mcp__revit_get_change_records",
      "mcp__rvt-mcp__revit_get_current_target",
      "mcp__rvt-mcp__revit_get_current_view_info",
      "mcp__rvt-mcp__revit_get_element_bounding_box",
      "mcp__rvt-mcp__revit_get_element_centroid",
      "mcp__rvt-mcp__revit_get_element_details",
      "mcp__rvt-mcp__revit_get_element_geometry",
      "mcp__rvt-mcp__revit_get_element_parameters",
      "mcp__rvt-mcp__revit_get_element_relationships",
      "mcp__rvt-mcp__revit_get_failure_records",
      "mcp__rvt-mcp__revit_get_family_instances",
      "mcp__rvt-mcp__revit_get_group_members",
      "mcp__rvt-mcp__revit_get_link_coordinate_system",
      "mcp__rvt-mcp__revit_get_link_elements",
      "mcp__rvt-mcp__revit_get_material_properties",
      "mcp__rvt-mcp__revit_get_material_quantities",
      "mcp__rvt-mcp__revit_get_mep_element_connectors",
      "mcp__rvt-mcp__revit_get_model_warnings_summary",
      "mcp__rvt-mcp__revit_get_operation_status",
      "mcp__rvt-mcp__revit_get_panel_schedule",
      "mcp__rvt-mcp__revit_get_print_settings",
      "mcp__rvt-mcp__revit_get_project_coordinate_system",
      "mcp__rvt-mcp__revit_get_room_boundaries",
      "mcp__rvt-mcp__revit_get_room_openings",
      "mcp__rvt-mcp__revit_get_schedulable_fields",
      "mcp__rvt-mcp__revit_get_schedule_data",
      "mcp__rvt-mcp__revit_get_schedule_definition",
      "mcp__rvt-mcp__revit_get_schedule_formulas",
      "mcp__rvt-mcp__revit_get_selected_elements",
      "mcp__rvt-mcp__revit_get_structural_loads",
      "mcp__rvt-mcp__revit_get_system_inventory",
      "mcp__rvt-mcp__revit_get_titleblock_parameters",
      "mcp__rvt-mcp__revit_get_type_parameters",
      "mcp__rvt-mcp__revit_get_view_visibility",
      "mcp__rvt-mcp__revit_get_viewport_geometry",
      "mcp__rvt-mcp__revit_health",
      "mcp__rvt-mcp__revit_list_areas",
      "mcp__rvt-mcp__revit_list_assemblies",
      "mcp__rvt-mcp__revit_list_available_targets",
      "mcp__rvt-mcp__revit_list_baked_tools",
      "mcp__rvt-mcp__revit_list_export_settings",
      "mcp__rvt-mcp__revit_list_family_types_in_family",
      "mcp__rvt-mcp__revit_list_groups",
      "mcp__rvt-mcp__revit_list_keynotes",
      "mcp__rvt-mcp__revit_list_linked_cad",
      "mcp__rvt-mcp__revit_list_linked_models",
      "mcp__rvt-mcp__revit_list_loaded_families",
      "mcp__rvt-mcp__revit_list_materials",
      "mcp__rvt-mcp__revit_list_mep_systems",
      "mcp__rvt-mcp__revit_list_phases",
      "mcp__rvt-mcp__revit_list_project_parameter_bindings",
      "mcp__rvt-mcp__revit_list_project_parameters",
      "mcp__rvt-mcp__revit_list_rebar",
      "mcp__rvt-mcp__revit_list_recent_models",
      "mcp__rvt-mcp__revit_list_revisions",
      "mcp__rvt-mcp__revit_list_rooms",
      "mcp__rvt-mcp__revit_list_saved_selections",
      "mcp__rvt-mcp__revit_list_schedules",
      "mcp__rvt-mcp__revit_list_shared_parameters",
      "mcp__rvt-mcp__revit_list_sheets",
      "mcp__rvt-mcp__revit_list_titleblocks",
      "mcp__rvt-mcp__revit_list_view_filters",
      "mcp__rvt-mcp__revit_list_view_templates",
      "mcp__rvt-mcp__revit_list_worksets",
      "mcp__rvt-mcp__revit_load_selection",
      "mcp__rvt-mcp__revit_lookup_message",
      "mcp__rvt-mcp__revit_measure_distance_between_elements",
      "mcp__rvt-mcp__revit_project_point_onto_face",
      "mcp__rvt-mcp__revit_raycast_from_point",
      "mcp__rvt-mcp__revit_select_elements",
      "mcp__rvt-mcp__revit_show_element_in_view",
      "mcp__rvt-mcp__revit_show_message",
      "mcp__rvt-mcp__revit_suggest_view_name_corrections",
      "mcp__rvt-mcp__revit_survey_change_impact",
      "mcp__rvt-mcp__revit_workflow_model_audit"
    ]
  }
}

send_code 默认开启，且独立于 ToolBaker；调用日志默认关闭。CLI 优先级高于环境变量，环境变量优先级高于 JSON。经过身份验证的服务设置仅对该请求覆盖插件设置。关闭调用日志后，服务日志、插件的 mcp-calls.jsonl 和 send-code 正文日志都会被抑制；内存中的 History 仍可用。正文日志记录需要同时开启调用日志和单独的 TTL 选择加入。ToolBaker 的 usage.jsonl 独立运行，并遵循自适应烘焙设置。

网关和 Revit 加载项的诊断信息共用 %LOCALAPPDATA%\Bimwright\rvt-mcp\rvt-mcp.log：10 MiB，另加一个 10 MiB 备份。条目包含 UTC 日期、进程 ID 和 Revit 年份；重复消息会汇总。日志使用有界后台队列，因此文件被锁定或磁盘速度较慢时，诊断信息可能丢失，但不会阻塞 Revit。已知的旧版 revit-mcp.log、debug.log 和 baked/compile-refs.log 文件仅保留末尾 64 KiB；运行时数据迁移期间不再复制这些文件。

调用日志、每日日志、send-code 日志、使用记录和烘焙审计记录各自最多保留 30 天 / 每组 100 MiB。新文件会在追加操作导致大小超过 5 MiB 时以及 UTC 日期变更时轮转；启动维护和后续写入会在需要时删除最旧的生成归档。使用情况分析仍最多覆盖 21 天和最近 5,000 条记录。send-code 正文 TTL 仍是额外且更短的限制。维护只识别生成的日志名称，不会跟随链接文件或文件夹；模型、配置和数据库不在其范围内。

响应保护默认开启：UTF-8 警告阈值为 65536 字节，强警告阈值为 262144 字节以上，预算为 716800 字节，传输上限为 1048576 字节。JSON 转义以及 MCP 内容/元数据均在服务端测量。超大读取会返回 RESPONSE_TOO_LARGE 并提供缩小范围的建议；已完成的写入会返回简要摘要。任意代码的输出会写入本地文件，并将 mutation_applied 设为 null；应检查该文件，而不是重新运行命令。溢出文件默认保留 36 小时（--spill-retention-hours，范围为 1-8760；无效值按 36 处理），文件数量上限不会删除尚未到期的文件。关闭保护后，传输上限仍然生效。字节限制必须是 >=1024 的整数，且顺序为 warn <= strong <= budget <= max；降低预算时，应相应调低阈值。

支持的 Revit 版本

仅支持完整的 Revit 桌面版；Revit Viewer 不是受支持的目标。CI 会构建全部六个加载项，但各年份的运行时支持深度有所不同——请在你使用的 Revit 年份中重新检查烘焙工具和自定义 C#。

多个 Revit 实例

服务会精准绑定到一个 Revit 实例，即使同时运行多个同年份的实例也是如此。只有恰好有一个实例匹配时，查询才能自动绑定。多个匹配项会返回 AMBIGUOUS_TARGET；模型/文件写入需要先选择目标，模型写入还需要验证文档。选择器：auto、4 位年份（2024）、pid:<n> 或 id:revit-<year>-<pid>；不接受旧版 R 代码（如 R24）。

同时运行多个实例时，尤其是多个同年份实例时，不要猜测目标。在可写会话中：

1. 调用 revit_list_available_targets：系统会列出每个正在运行的实例及其 target_id、pid、host_year、window_title 和 source。
2. 根据 pid 和/或 window_title 选择实例。
3. 使用 revit_switch_target(version="pid:<n>", verify=false) 选择进程，查询其活动视图/文档，然后使用 revit_switch_target(version="pid:<n>", verify=true, expectedDocumentId="<document_id>") 确认。请从查询返回的 _target 标记中复制标识。首次确认时，省略 expectedDocumentId 即可确认验证探测所报告的文档。同一进程内切换会保留之前的文档约束，包括通过 verify=false 切换时；若要确认另一个文档，必须提供其 expectedDocumentId 或设置 rebind=true。只有匹配实例恰好一个时才接受 auto/年份选择器。
4. revit_get_current_target 会显示绑定、代次、selection_confirmed、confirmed_document_id、expected_document_id（待确认时必须匹配的文档）以及 confirmation_required。成功的主机响应会携带 _target，其中包含实际 PID、年份和文档标识，即使响应经过精简也会保留这些信息。

会话建立绑定后，auto/年份选择器不能将其切换到另一个实例，无论之前的实例是已退出、已重启，还是仅停止了 MCP 监听器：即使只剩一个匹配实例，也不足以确认。请使用 pid:/id: 选择新实例；当只剩一个候选项时，目标错误的 next_step 会指出其 pid:<n>。离开仍在运行且已确认的实例还需要设置 rebind=true。新会话中的首次选择仍接受 auto/年份选择器，前提是恰好有一个实例匹配。每次接受切换都会推进代次，确保较早的调用不能采用之后的确认结果。如果验证失败，且期间没有更新的切换操作，则会恢复之前仍在运行的绑定。已关闭后重新打开的文档、另一个项目或“编辑族”操作具有不同的文档标识；每次执行写入前，加载项都会在 Revit UI 线程上检查预期标识。读取其他文档不会更改写入锁定的目标。写入前请检查并确认该文档。open_model 会建立文档：使用 verify=false 选择进程，打开模型，然后验证其 expectedDocumentId（或使用 rebind=true 替换之前确认的文档）。该操作不能在 batch_execute 中运行。

可写会话中的目标错误代码及恢复方法。只读会话请使用下方的启动/重启方式。除 TARGET_INTERRUPTED 外，所有代码都表示命令未发送：

重启 Revit 后——即使只打开了一个 Revit 实例——可写会话也会返回 TARGET_CHANGED，并等待一次 revit_switch_target(version="pid:<n>") 调用，然后才会发送任何内容。重启后的 Revit 可能打开了不同的模型；请检查建议的实例、确认后再重复调用。

**只读会话：**调用 revit_list_available_targets，在网关启动时选择 --target pid:<n>，并在目标更改时重启网关。revit_switch_target 不可用；上述目标错误会提供启动/重启指引，而不是建议使用该工具。

revit_switch_target 会更改会话路由，并因其非只读注解而被排除在 --read-only 之外。只读模式在包含所有工具集的情况下提供 98 个工具。在网关启动时使用 --read-only --target pid:<n> 选择预期进程；如需更改，请使用新的选择器重启网关。revit_list_available_targets 和 revit_get_current_target 仍可用于检查。

DOCUMENT_UNCONFIRMED 和 DOCUMENT_CHANGED 是加载项拒绝请求：请求已到达 Revit，但模型操作尚未开始。检查报告的 _target，然后确认预期文档。网关和加载项都必须支持 document_target_v1；请一并更新。如果加载项连接到较旧的网关，则会返回 PAIRING_REQUIRED；请更新服务端，因为该网关无法确认文档。

安全与隐私

• 默认使用本地连接：通过环回 TCP 或本地命名管道，并在 %LOCALAPPDATA%\Bimwright\rvt-mcp\ 下的发现文件中存储每个会话的身份验证令牌。
• 工具处理程序运行前会对工具参数进行架构检查；返回给模型的错误会经过净化处理。
• send_code 会在 Revit 进程中运行任意 C# 代码，功能强大但风险较高。如果无法接受此风险，请使用 --read-only 或 --disable-send-code。
• 自适应烘焙、主体缓存和 send_code 日志均为可选功能，数据保存在你的用户配置文件下；默认情况下，不会将原始 send_code 主体写入长期日志。

更多信息：SECURITY.md、docs/bake.md。

文档

社区贡献

代码、错误报告、可复现示例和提案都有助于改进 rvt-mcp。感谢以下贡献者：

bimwright 家族

将 AI 助手连接到 BIM 和 CAD 应用的开源工具。

名称 bimwright 由 BIM 和 wright 组合而成；后者是一个古老的词，意为制造者或建造者，例如 shipwright（造船工）。

查看网关名称的选取方式。

• rvt-mcp — Autodesk® Revit®
• dwg-mcp — Autodesk® AutoCAD®
• nwd-mcp — Autodesk® Navisworks®
• ipt-mcp — Autodesk® Inventor®
• bim-wiki — 越南语优先的 BIM 知识库

验证

请参阅工具描述符基准测试和 v1.2.0 验证记录。两者区分了受影响的回归测试结果、较早的原生证据以及待完成的发布覆盖；描述符字节数无法衡量模型 token 数或原生性能。

许可证

Apache-2.0 — LICENSE。

欢迎分叉和重新命名——只需遵守许可证条款（保留 LICENSE 和版权声明，并标明修改过的文件）。如果 rvt-mcp 对你有所帮助，欢迎点星或在你的产品中提及 BIMwright，但这完全是可选的。始终欢迎提交问题和 PR。

Revit 和 Autodesk 是 Autodesk, Inc. 的商标。bimwright 是独立的开源项目，与 Autodesk, Inc. 无关，也未获得其赞助或认可。