金大哥 - mcp-servers-for-revit MCP 详情

article

README

🚀 Revit模型上下文协议服务器

通过模型上下文协议（MCP）将AI助手连接到Autodesk Revit。

mcp-servers-for-revit使Claude、Cline等AI客户端以及其他支持MCP的工具能够读取、创建、修改和删除Revit项目中的元素。它由三个组件组成：一个将工具暴露给AI的TypeScript MCP服务器、一个将命令桥接到Revit的C# Revit插件，以及一组实现实际Revit API操作的命令集。

⚠️ 重要提示

本项目是原 revit-mcp 项目的分支，增加了额外的工具并改进了功能。

🚀 快速开始

使用发布版本

从发布页面下载适合你Revit版本的ZIP文件（例如，mcp-servers-for-revit-v1.0.0-Revit2025.zip）。

解压ZIP文件，并将内容复制到你的Revit插件文件夹：

%AppData%\Autodesk\Revit\Addins\<你的Revit版本>\

复制后，你应该看到以下结构：

Addins/2025/
├── mcp-servers-for-revit.addin
└── revit_mcp_plugin/
    ├── revit-mcp-plugin.dll
    ├── ...
    └── Commands/
        └── RevitMCPCommandSet/
            ├── command.json
            └── 2025/
                ├── RevitMCPCommandSet.dll
                └── ...

在你的AI客户端中配置MCP服务器（见下文）。
启动Revit - 插件将自动加载。

MCP服务器设置

MCP服务器作为npm包发布，可以直接使用 npx 运行。

Claude代码

claude mcp add mcp-server-for-revit -- cmd /c npx -y mcp-server-for-revit

Claude桌面版 Claude桌面版 → 设置 → 开发者 → 编辑配置 → claude_desktop_config.json：

{
    "mcpServers": {
        "mcp-server-for-revit": {
            "command": "cmd",
            "args": ["/c", "npx", "-y", "mcp-server-for-revit"]
        }
    }
}

重启Claude桌面版。当你看到锤子图标时，MCP服务器已连接。

Claude桌面版连接

Revit插件设置

如果使用发布的ZIP文件，插件已经包含在内。如需手动安装：

从 plugin/ 目录构建插件（见开发）。
将 mcp-servers-for-revit.addin 复制到 %AppData%\Autodesk\Revit\Addins\<版本>\。
将 revit_mcp_plugin/ 文件夹复制到同一个插件目录。

命令集设置

如果使用发布的ZIP文件，命令集已预先安装在插件中。如需手动安装：

从 commandset/ 目录构建命令集（见开发）。
在插件的安装目录中创建 Commands/RevitMCPCommandSet/<年份>/。
将构建好的DLL文件复制到该文件夹。
将 command.json（从仓库根目录）复制到 Commands/RevitMCPCommandSet/。

✨ 主要特性

多工具支持：支持Claude、Cline等多种AI客户端以及其他MCP兼容工具。
丰富的操作功能：可以对Revit项目中的元素进行读取、创建、修改和删除等操作。
模块化设计：由MCP服务器、Revit插件和命令集三个组件组成，结构清晰。

📦 安装指南

环境要求

Node.js 18+（用于MCP服务器）
Autodesk Revit 2020 - 2026（任何受支持的版本）

安装步骤

按照上述快速开始中的步骤进行安装。

💻 使用示例

基础用法

# 在Claude中添加MCP服务器
claude mcp add mcp-server-for-revit -- cmd /c npx -y mcp-server-for-revit

高级用法

// 在Claude桌面版中配置MCP服务器
{
    "mcpServers": {
        "mcp-server-for-revit": {
            "command": "cmd",
            "args": ["/c", "npx", "-y", "mcp-server-for-revit"]
        }
    }
}

📚 详细文档

支持的工具

| 工具 | 描述 | | ---- | ----------- | | get_current_view_info | 获取当前活动视图信息 | | get_current_view_elements | 获取当前活动视图中的元素 | | get_available_family_types | 获取当前项目中可用的族类型 | | get_selected_elements | 获取当前选中的元素 | | get_material_quantities | 计算材料数量和清单 | | ai_element_filter | 为AI助手提供的智能元素查询工具 | | analyze_model_statistics | 通过元素计数分析模型复杂度 | | create_point_based_element | 创建基于点的元素（门、窗、家具） | | create_line_based_element | 创建基于线的元素（墙、梁、管道） | | create_surface_based_element | 创建基于面的元素（地板、天花板、屋顶） | | create_grid | 创建具有智能间距生成的网格系统 | | create_level | 在指定高度创建楼层 | | create_room | 在指定位置创建并放置房间 | | create_dimensions | 在当前视图中创建尺寸标注 | | create_structural_framing_system | 创建结构梁框架系统 | | delete_element | 按ID删除元素 | | operate_element | 对元素进行操作（选择、设置颜色、隐藏等） | | color_elements | 根据参数值为元素着色 | | tag_all_walls | 为当前视图中的所有墙添加标签 | | tag_all_rooms | 为当前视图中的所有房间添加标签 | | export_room_data | 导出项目中的所有房间数据 | | store_project_data | 将项目元数据存储到本地数据库 | | store_room_data | 将房间元数据存储到本地数据库 | | query_stored_data | 查询存储的项目和房间数据 | | send_code_to_revit | 将C#代码发送到Revit执行 | | say_hello | 在Revit中显示问候对话框（连接测试） |

测试

测试项目使用 Nice3point.TUnit.Revit 对实时Revit实例运行集成测试。无需单独安装插件 — 框架会自动注入正在运行的Revit进程。

前提条件

.NET 10 SDK — Nice3point.Revit.Sdk 6.1.0 需要此SDK。通过 winget install Microsoft.DotNet.SDK.10 进行安装。
Autodesk Revit 2026（或2025） — 必须安装并在你的机器上获得许可。

运行测试

打开Revit 2026（或2025）并等待其完全加载。
从命令行运行测试：

# 对于Revit 2026
dotnet test -c Debug.R26 -r win-x64 tests/commandset

# 对于Revit 2025
dotnet test -c Debug.R25 -r win-x64 tests/commandset

注意：在ARM64机器上，-r win-x64 标志是必需的，因为Revit API程序集仅支持x64。

或者，你可以使用 dotnet run：

cd tests/commandset
dotnet run -c Debug.R26

IDE支持

JetBrains Rider — 在设置 > 构建、执行、部署 > 单元测试 > 测试平台中启用“测试平台支持”。
Visual Studio — 测试应该可以通过标准的测试资源管理器发现。

测试结构

| 目录 | 用途 | |-----------|---------| | tests/commandset/AssemblyInfo.cs | 全局 [assembly: TestExecutor<RevitThreadExecutor>] 注册 | | tests/commandset/Architecture/ | 楼层和房间创建命令的测试 | | tests/commandset/DataExtraction/ | 模型统计、房间数据导出和材料数量的测试 | | tests/commandset/ColorSplashTests.cs | 颜色覆盖功能的测试 | | tests/commandset/TagRoomsTests.cs | 房间标签功能的测试 |

编写新测试

测试类继承自 RevitApiTest 并使用TUnit的异步断言API：

public class MyTests : RevitApiTest
{
    private static Document _doc;

    [Before(HookType.Class)]
    [HookExecutor<RevitThreadExecutor>]
    public static void Setup()
    {
        _doc = Application.NewProjectDocument(UnitSystem.Imperial);
    }

    [After(HookType.Class)]
    [HookExecutor<RevitThreadExecutor>]
    public static void Cleanup()
    {
        _doc?.Close(false);
    }

    [Test]
    public async Task MyTest_Condition_ExpectedResult()
    {
        var elements = new FilteredElementCollector(_doc)
            .WhereElementIsNotElementType()
            .ToElements();

        await Assert.That(elements.Count).IsGreaterThan(0);
    }
}

🔧 技术细节

架构

flowchart LR
    Client["MCP客户端<br/>(Claude, Cline等)"]
    Server["MCP服务器<br/><code>server/</code>"]
    Plugin["Revit插件<br/><code>plugin/</code>"]
    CommandSet["命令集<br/><code>commandset/</code>"]
    Revit["Revit API"]

    Client <-->|标准输入输出| Server
    Server <-->|WebSocket| Plugin
    Plugin -->|加载| CommandSet
    CommandSet -->|执行| Revit

MCP服务器（TypeScript）将AI客户端的工具调用转换为WebSocket消息。Revit插件（C#）在Revit内部运行，监听这些消息，并将它们分发给命令集（C#），命令集执行实际的Revit API操作并将结果返回。

开发

MCP服务器

cd server
npm install
npm run build

服务器将TypeScript编译到 server/build/。在开发过程中，你可以直接使用 npx tsx server/src/index.ts 运行它。

Revit插件 + 命令集

在Visual Studio中打开 mcp-servers-for-revit.sln。该解决方案包含插件和命令集项目。构建配置针对Revit 2020 - 2026：

Revit 2020 - 2024：.NET Framework 4.8（Release R20 到 Release R24）
Revit 2025 - 2026：.NET 8（Release R25，Release R26）构建解决方案会自动在 plugin/bin/AddIn <年份> <配置>/ 中组装完整的可部署布局 — 命令集会作为构建的一部分复制到插件的 Commands/ 文件夹中。

项目结构

mcp-servers-for-revit/
├── mcp-servers-for-revit.sln    # 组合解决方案（插件 + 命令集 + 测试）
├── command.json     # 命令集清单
├── server/          # MCP服务器（TypeScript） - 向AI客户端暴露的工具
├── plugin/          # Revit插件（C#） - Revit内部的WebSocket桥接器
├── commandset/      # 命令实现（C#） - Revit API操作
├── tests/           # 集成测试（C#） - 针对实时Revit的TUnit测试
├── assets/          # 文档图片
├── .github/         # CI/CD工作流、贡献指南、行为准则
├── LICENSE
└── README.md

发布

单个 v* 标签驱动整个发布过程。发布工作流会自动执行以下操作：

为Revit 2020 - 2026构建Revit插件和命令集。
创建一个GitHub发布，包含 mcp-servers-for-revit-vX.Y.Z-Revit<年份>.zip 资产。
将MCP服务器发布到npm，包名为 mcp-server-for-revit。

要创建发布：

运行版本更新脚本（更新 server/package.json、server/package-lock.json 和 plugin/Properties/AssemblyInfo.cs，然后提交并打标签）：
```
./scripts/release.ps1 -Version X.Y.Z
```
推送以触发工作流：
```
git push origin main --tags
```

⚠️ 重要提示

npm发布使用可信发布通过OIDC进行 — 无需npm令牌。出处证明会自动生成。

📄 许可证

MIT

致谢

本项目是 mcp-servers-for-revit 团队工作的分支。原始仓库如下：

revit-mcp - MCP服务器
revit-mcp-plugin - Revit插件
revit-mcp-commandset - 命令集

感谢原始作者创建了本项目的基础。

mcp-servers-for-revit