Skip to content
Back to search

aec-model-bridge

Independent Revit MCP ( Model Context Protocol integration for Revit software ).

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 17 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Sam-AEC/aec-model-bridge with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Sam-AEC/aec-model-bridge'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/sam-aec--aec-model-bridge/badge.svg)](/listings/sam-aec--aec-model-bridge)

HTML

<a href="/listings/sam-aec--aec-model-bridge"><img src="/api/listings/sam-aec--aec-model-bridge/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**In 60 seconds, without Revit (mock mode)**

1. Install [uv](https://docs.astral.sh/uv/getting-started/installation/). 2. Add the server to your client with the JSON under Manual setup and set `"MCP_REVIT_MODE": "mock"`. The one-click buttons below start in `bridge` mode, which needs Revit. 3. Restart the client and ask it to list the AEC Model Bridge tools. 4. Ask it to read the active document. Mock mode returns generated sample data, never your model, so the answers are a way to see the tools and the approval flow before you connect Revit. 5. For your own model, install the Revit add-in ([install steps](#install-the-revit-add-in)) and switch the mode to `bridge`.

**One-click install**

The buttons need [uv](https://docs.astral.sh/uv/getting-started/installation/) and nothing else. The server uses `~/Documents/AEC Model Bridge` as its workspace unless you set your own. For Claude Desktop, download the `.mcpb` file from the latest release and open it. Live Revit work still needs Revit and [the add-in](#install-the-revit-add-in). Mock mode needs neither.

**Manual setup**

For live Revit automation you need Windows, a licensed Revit 2024 to 2027, Python 3.11 or newer, [uv](https://docs.astral.sh/uv/getting-started/installation/), and the Revit add-in ([install steps](#install-the-revit-add-in)). Then add this to your `claude_desktop_config.json` (Codex, Cursor and VS Code use the same values; the two directory variables are optional and default to the workspace above):

{
  "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"
      }
    }
  }
}

Want to look at the tools first, without Revit? Set `"MCP_REVIT_MODE": "mock"`. The server then starts on any machine, lists every tool with its schema and returns canned responses. It does not touch a model. A `Dockerfile` for the same mock mode is in the repository root (`docker build -t aec-model-bridge .`, then `docker run -i --rm aec-model-bridge`).

Using VS Code? The [extension source and local install steps](extensions/vscode/README.md) register the MCP server and show the Revit connection status. It has not been published to the Marketplace.

Tools at a glance

| Area | Tools | What they do | | --- | --- | --- | | Revit | 110 | Read the model, create and edit elements, parameters, views, sheets, schedules, exports, worksharing | | Approval | 5 | Plan, review, approve, execute and roll back model changes | | Modules | 108 | Snapshot inspection, parameter grids, QA/QC checks, recipes, reports, selections | | Rhino and Grasshopper | 19 | Geometry, layers, materials, boolean operations | | Speckle | 17 | Projects, models, versions, send and receive | | Navisworks | 15 | Model tree, viewpoints, clash tests (in progress) | | IFC | 7 | Read IFC files without Revit: structure, properties, validation | | Graph, snapshots, exports, jobs | 21 | Semantic graph audits, snapshot diffs, SQLite export, background jobs |

302 tools are listed in the default setup (counted from the current server in mock mode). The Autodesk Data tools appear when APS credentials are configured. The [tool reference](docs/tools-generated.md) lists every tool. Each tool carries MCP annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`), so clients can tell reads from writes.

Advanced Revit automation

Alongside model queries and parameter updates, Revit tools create building elements, views, sheets, schedules, tags and dimensions, and export IFC, DWG, images and Navisworks files. See the [tool reference](docs/tools-generated.md) for supported operations and inputs.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 21 lines
  1. {
  2. "name": "aec-model-bridge",
  3. "owner": {
  4. "name": "A. Sam Mohammad",
  5. "url": "https://github.com/Sam-AEC"
  6. },
  7. "metadata": {
  8. "description": "AEC Model Bridge for Claude Code: read an open Revit model and propose changes that a person approves first."
  9. },
  10. "plugins": [
  11. {
  12. "name": "aec-model-bridge",
  13. "source": "./plugin",
  14. "description": "Revit MCP server with an approval gate, plus a skill for the safe read, check, propose, approve flow.",
  15. "version": "1.5.0",
  16. "license": "GPL-3.0-or-later",
  17. "homepage": "https://github.com/Sam-AEC/aec-model-bridge",
  18. "keywords": ["revit", "bim", "aec", "mcp", "autodesk"]
  19. }
  20. ]
  21. }
README.md · README · 569 lines
  1. <div align="center">
  2. <img src="assets/logo.svg" alt="AEC Model Bridge logo: an isometric model cube with a bridge arch" height="120">
  3. **English** | [简体中文](docs/i18n/README.zh-CN.md) | [Español](docs/i18n/README.es.md) | [हिन्दी](docs/i18n/README.hi.md) | [العربية](docs/i18n/README.ar.md) | [Português (BR)](docs/i18n/README.pt-BR.md) | [Русский](docs/i18n/README.ru.md) | [日本語](docs/i18n/README.ja.md) | [Deutsch](docs/i18n/README.de.md) | [Français](docs/i18n/README.fr.md) | [Bahasa Indonesia](docs/i18n/README.id.md) | [Türkçe](docs/i18n/README.tr.md) | [한국어](docs/i18n/README.ko.md) | [Tiếng Việt](docs/i18n/README.vi.md) | [Italiano](docs/i18n/README.it.md) | [Polski](docs/i18n/README.pl.md) | [繁體中文](docs/i18n/README.zh-TW.md)
  4. **Ask your AI about the Revit model you have open. By default, write tools are blocked until you approve a plan.**
  5. Open-source MCP server and native add-in for Revit 2024 – 2027. Works with Claude, Codex and other MCP clients.
  6. [![CI](https://img.shields.io/github/actions/workflow/status/Sam-AEC/aec-model-bridge/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/Sam-AEC/aec-model-bridge/actions/workflows/ci.yml)
  7. [![Release](https://img.shields.io/github/v/release/Sam-AEC/aec-model-bridge?style=flat-square&color=0F766E)](https://github.com/Sam-AEC/aec-model-bridge/releases/latest)
  8. [![Revit](https://img.shields.io/badge/Revit-2024--2027-0696D7?style=flat-square)](#supported-revit-versions)
  9. [![License](https://img.shields.io/badge/license-GPL--3.0%20%2B%20commercial-2563EB?style=flat-square)](LICENSING.md)
  10. [Get started](#quick-start) | [Example workflows](#example-workflows) | [Tools](docs/tools-generated.md) | [Documentation](#documentation) | [Download](https://github.com/Sam-AEC/aec-model-bridge/releases/latest)
  11. </div>
  12. Status: on the dev branch, not yet released.
  13. <p align="center">
  14. <img src="docs/images/readme/revit-villa-panel.png" alt="Revit villa model beside the AEC Model Bridge panel with Dev mode enabled." width="900">
  15. </p>
  16. AEC Model Bridge is the open-source Revit MCP server that lets Claude, Codex,
  17. Cursor and other AI assistants read and edit your open Revit model. By default
  18. you approve every change first. It has two parts: a Python MCP server and a
  19. native Revit add-in. Read-only tools inspect the model straight away. Model
  20. changes need an approved plan by default.
  21. [See the approval flow](#how-approval-works).
  22. **Who it is for.** BIM coordinators and managers who want an AI assistant to
  23. check model quality, find affected elements and prepare parameter fixes, while a
  24. person stays in control of every change. You do not need to write scripts.
  25. **Status and limits.** This is pre-release software.
  26. - Bounded read-only checks in Revit 2024 are recorded in the
  27. [live validation report](docs/revit-addin-live-validation-2026-10-14.md).
  28. These checks do not establish that writes, rollback, recovery or other Revit
  29. years work. Those paths still need live acceptance. The Python server also
  30. has automated tests; CI builds do not start Revit. See the
  31. [release checklist](docs/release-checklist.md).
  32. - This page describes the dev branch. The latest GitHub release may not include
  33. everything described here.
  34. - Try it on a copy of a project first. Approving a plan changes the open model.
  35. - Some limits are known and listed under [How approval works](#how-approval-works)
  36. and in [docs/security.md](docs/security.md).
  37. ## Star History
  38. <a href="https://www.star-history.com/?repos=sam-aec%2Faec-model-bridge&type=date&legend=top-right">
  39. <picture>
  40. <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=sam-aec/aec-model-bridge&type=date&theme=dark&legend=bottom-right" />
  41. <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=sam-aec/aec-model-bridge&type=date&legend=bottom-right" />
  42. <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=sam-aec/aec-model-bridge&type=date&legend=bottom-right" />
  43. </picture>
  44. </a>
  45. Setup is documented for Claude Desktop, VS Code with GitHub Copilot, Cursor and
  46. Codex. The server is a standard MCP stdio server, so other clients such as
  47. Claude Code, Windsurf, Cline, Continue, Zed and Gemini CLI should work too. The
  48. [compatibility](docs/compatibility.md) page lists what is documented and what
  49. is untested.
  50. The same server also inspects IFC files, automates Rhino and Grasshopper, and
  51. connects to Speckle. [Integration status](#other-integrations) shows which
  52. providers are available and which are still in progress.
  53. ## Example workflows
  54. For BIM coordinators: check model quality, review the affected elements,
  55. approve a parameter fix, then check the result and export a report. These
  56. examples use tools in the [current catalog](docs/tools-generated.md).
  57. | Workflow | Example request | Tools used |
  58. | --- | --- | --- |
  59. | Model review | "Show the active document, list its warnings and find affected elements." | `revit_get_document_info`, `revit_get_warnings`, `revit_get_elements_by_type` |
  60. | Parameter updates | "Find walls on Level 02, show their Comments values, and propose a batch update." | `revit_get_elements_by_type`, `revit_get_element_parameters`, `revit_batch_set_parameters` |
  61. | Drawing production | "Prepare a sheet list from this CSV, then propose creating the sheets and placing the views." | `revit_batch_create_sheets_from_csv`, `revit_place_viewport_on_sheet` |
  62. | IFC review | "Show this IFC file's storeys, inspect the wall properties and report schema validation issues." | `ifc_get_spatial_structure`, `ifc_get_properties`, `ifc_validate` |
  63. For a first run in Revit, try:
  64. ```text
  65. Read the active model's warnings. Group them by description and show the
  66. affected element IDs. Then suggest which issues to investigate first.
  67. ```
  68. Then try a parameter correction, replacing the level and value for your project:
  69. ```text
  70. Find walls on Level 02 and show their current Comments values. Propose setting
  71. Comments to "Coordination reviewed" for the elements I choose. After I approve
  72. the plan in Revit, apply it and read the values back to confirm the result.
  73. ```
  74. For edits, the assistant creates a plan with `plan_actions`. You review it in
  75. the Revit panel, and only then does `execute_plan` apply it. IFC review runs
  76. without Revit.
  77. The snapshot QA/QC and report modules need a compatible saved snapshot. The
  78. handoff from Revit to these modules currently needs the filename and workspace
  79. to match. If you leave out `snapshot_id`, most of these modules now refuse in
  80. bridge mode with a clear message, and return generated sample data only in mock
  81. mode. Not every module has that guard yet (`model_bloat` does not), so always
  82. pass `snapshot_id`. For live inspection, use the direct Revit tools above.
  83. [Planned fixes and demo](docs/roadmap.md).
  84. ## Quick start
  85. **In 60 seconds, without Revit (mock mode)**
  86. 1. Install [uv](https://docs.astral.sh/uv/getting-started/installation/).
  87. 2. Add the server to your client with the JSON under Manual setup and set
  88. `"MCP_REVIT_MODE": "mock"`. The one-click buttons below start in `bridge`
  89. mode, which needs Revit.
  90. 3. Restart the client and ask it to list the AEC Model Bridge tools.
  91. 4. Ask it to read the active document. Mock mode returns generated sample
  92. data, never your model, so the answers are a way to see the tools and the
  93. approval flow before you connect Revit.
  94. 5. For your own model, install the Revit add-in
  95. ([install steps](#install-the-revit-add-in)) and switch the mode to
  96. `bridge`.
  97. **One-click install**
  98. [![Install in VS Code](https://img.shields.io/badge/Install_in-VS_Code-0098FF?style=for-the-badge)](docs/install-buttons.md#vs-code)
  99. [![Install in Cursor](https://img.shields.io/badge/Install_in-Cursor-111111?style=for-the-badge)](https://cursor.com/en/install-mcp?name=aec-model-bridge&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJnaXQraHR0cHM6Ly9naXRodWIuY29tL1NhbS1BRUMvYWVjLW1vZGVsLWJyaWRnZSNzdWJkaXJlY3Rvcnk9cGFja2FnZXMvbWNwLXNlcnZlci1yZXZpdCIsImFlYy1tb2RlbC1icmlkZ2UiXSwiZW52Ijp7Ik1DUF9SRVZJVF9NT0RFIjoiYnJpZGdlIn19)
  100. [![Claude Desktop bundle](https://img.shields.io/badge/Claude_Desktop-.mcpb_bundle-D97757?style=for-the-badge)](https://github.com/Sam-AEC/aec-model-bridge/releases/latest)
  101. The buttons need [uv](https://docs.astral.sh/uv/getting-started/installation/)
  102. and nothing else. The server uses `~/Documents/AEC Model Bridge` as its
  103. workspace unless you set your own. For Claude Desktop, download the `.mcpb`
  104. file from the latest release and open it. Live Revit work still needs Revit and
  105. [the add-in](#install-the-revit-add-in). Mock mode needs neither.
  106. **Manual setup**
  107. For live Revit automation you need Windows, a licensed Revit 2024 to 2027,
  108. Python 3.11 or newer, [uv](https://docs.astral.sh/uv/getting-started/installation/), and the Revit add-in
  109. ([install steps](#install-the-revit-add-in)). Then add this to your
  110. `claude_desktop_config.json` (Codex, Cursor and VS Code use the same values;
  111. the two directory variables are optional and default to the workspace above):
  112. ```json
  113. {
  114. "mcpServers": {
  115. "aec-model-bridge": {
  116. "command": "uvx",
  117. "args": [
  118. "--from",
  119. "git+https://github.com/Sam-AEC/aec-model-bridge#subdirectory=packages/mcp-server-revit",
  120. "aec-model-bridge"
  121. ],
  122. "env": {
  123. "MCP_REVIT_MODE": "bridge",
  124. "MCP_REVIT_WORKSPACE_DIR": "C:\\RevitProjects",
  125. "MCP_REVIT_ALLOWED_DIRECTORIES": "C:\\RevitProjects"
  126. }
  127. }
  128. }
  129. }
  130. ```
  131. Want to look at the tools first, without Revit? Set `"MCP_REVIT_MODE": "mock"`.
  132. The server then starts on any machine, lists every tool with its schema and
  133. returns canned responses. It does not touch a model. A `Dockerfile` for the same mock
  134. mode is in the repository root (`docker build -t aec-model-bridge .`, then
  135. `docker run -i --rm aec-model-bridge`).
  136. Using VS Code? The [extension source and local install steps](extensions/vscode/README.md)
  137. register the MCP server and show the Revit connection status. It has not been
  138. published to the Marketplace.
  139. ### Tools at a glance
  140. | Area | Tools | What they do |
  141. | --- | --- | --- |
  142. | Revit | 110 | Read the model, create and edit elements, parameters, views, sheets, schedules, exports, worksharing |
  143. | Approval | 5 | Plan, review, approve, execute and roll back model changes |
  144. | Modules | 108 | Snapshot inspection, parameter grids, QA/QC checks, recipes, reports, selections |
  145. | Rhino and Grasshopper | 19 | Geometry, layers, materials, boolean operations |
  146. | Speckle | 17 | Projects, models, versions, send and receive |
  147. | Navisworks | 15 | Model tree, viewpoints, clash tests (in progress) |
  148. | IFC | 7 | Read IFC files without Revit: structure, properties, validation |
  149. | Graph, snapshots, exports, jobs | 21 | Semantic graph audits, snapshot diffs, SQLite export, background jobs |
  150. 302 tools are listed in the default setup (counted from the current server in mock
  151. mode). The Autodesk Data tools appear when APS credentials are configured. The
  152. [tool reference](docs/tools-generated.md) lists every tool. Each tool carries
  153. MCP annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`,
  154. `openWorldHint`), so clients can tell reads from writes.
  155. ### Advanced Revit automation
  156. Alongside model queries and parameter updates, Revit tools create building
  157. elements, views, sheets, schedules, tags and dimensions, and export IFC, DWG,
  158. images and Navisworks files. See the [tool reference](docs/tools-generated.md)
  159. for supported operations and inputs.
  160. For anything the tool catalog does not cover, `revit_invoke_method`,
  161. `revit_reflect_get` and `revit_reflect_set` work with public Revit API members.
  162. `revit_execute_python` runs IronPython inside Revit. These advanced tools have
  163. the same permissions as the Revit process. Use them only with MCP clients and
  164. prompts you trust.
  165. ## How it works
  166. The MCP client talks to one Python hub. The hub sends each call to the
  167. provider that owns the tool. Providers for desktop apps talk to a small add-in
  168. inside that app over localhost.
  169. <p align="center">
  170. <picture>
  171. <source media="(prefers-color-scheme: dark)" srcset="docs/images/architecture-dark.png">
  172. <img src="docs/images/architecture-light.png" alt="Architecture of AEC Model Bridge: an MCP client such as Claude or Codex calls the Python MCP hub, which routes tool calls to the Revit, Rhino, Navisworks, IFC and Speckle providers. The Revit and Rhino providers talk to add-ins over localhost HTTP, the IFC provider reads IFC files with IfcOpenShell, and Navisworks is still in progress." width="900">
  173. </picture>
  174. </p>
  175. <sub>Diagram source: [architecture.mmd](docs/diagrams/architecture.mmd). Regenerate the images with `python scripts/render_diagrams.py`.</sub>
  176. Teal boxes work today. The amber dashed boxes are in progress. Indigo
  177. shapes are data and external services.
  178. ### How approval works
  179. In plain words:
  180. - **Two modes you will use.** `look_only` lets the assistant read but refuses
  181. every tool that changes the model. `ask_first` (the default, also written
  182. `required`) lets it draft changes, but nothing runs until a person approves.
  183. A third value, `auto`, switches the check off and is meant only for
  184. controlled pipelines.
  185. - **Only a person approves.** Approving, rejecting and rolling back plans are
  186. not offered to AI clients. A person approves in the Revit panel or with the
  187. `aec-model-bridge-approve` command.
  188. - **Nothing applies on its own.** A change runs only if it matches an approved
  189. action of an approved plan, once.
  190. - **Undo is per action.** Revit's Ctrl+Z undoes one action per press.
  191. The hub stops any tool call that changes the model unless it carries an
  192. approved plan. The AI proposes a plan, you review it, and the add-in runs it on
  193. Revit's main thread. The panel's Plans list shows each pending plan's tools,
  194. arguments and, when one was captured, the before-value. When a plan carries
  195. review text (reasoning, citations, assumptions or warnings), the card offers
  196. "Show the review to enable Approve" and requires you to open it before approval.
  197. Malformed, unsupported or oversized reviews block approval. If the panel cannot
  198. show the approved content completely, it disables Approve and points to
  199. `aec-model-bridge-approve show <plan_id>` for the full plan. See
  200. [plan review in the panel](docs/security.md#plan-review-in-the-panel).
  201. This UI is covered by automated browser checks; live WebView2 approval still
  202. needs acceptance. Parameter and model-edit actions each run in their own named
  203. transaction; some actions (save, sync, scripts) do not, so Ctrl+Z does not
  204. cover them.
  205. <p align="center">
  206. <picture>
  207. <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Sam-AEC/aec-model-bridge/main/docs/images/readme/readme-workflow-dark.png">
  208. <img src="https://raw.githubusercontent.com/Sam-AEC/aec-model-bridge/main/docs/images/readme/readme-workflow-light.png" alt="Inspect, Propose, Approve, Verify. Four steps: inspect finds an empty Mark, propose drafts a change, approve is a human decision, verify reads the value back. Example values are illustrative." width="900">
  209. </picture>
  210. </p>
  211. <p align="center">
  212. <picture>
  213. <source media="(prefers-color-scheme: dark)" srcset="docs/images/approval-flow-dark.png">
  214. <img src="docs/images/approval-flow-light.png" alt="Approval flow: the AI assistant drafts a plan with plan_actions, the side panel shows the proposed changes (counts, scope, before and after), and a human approves in the panel or with the aec-model-bridge-approve CLI, never over MCP. The hub checks that the plan matches the approved tool and arguments, once only. Revit then runs each action in its own transaction, so Ctrl+Z undoes one action per press. If you reject or never approve, the call is blocked and the model stays untouched." width="900">
  215. </picture>
  216. </p>
  217. <sub>Diagram source: [approval-flow.mmd](docs/diagrams/approval-flow.mmd). Regenerate the images with `python scripts/render_diagrams.py`.</sub>
  218. If a plan turns out wrong, undo it with Revit's Ctrl+Z. Each parameter write is
  219. its own named transaction, so one plan can take several presses. A one-step undo
  220. for a whole plan is planned, not built. A second route is a revert plan: the
  221. assistant drafts one with `plan_revert` from the proof of an executed plan, and
  222. you approve it like any other plan. `rollback_plan` also writes the recorded
  223. before-values back in reverse order and can skip an action when no before-value
  224. was recorded, but it is for people only and has no panel button or command-line
  225. command yet, so do not count on it. None of these paths is verified in a live
  226. Revit session yet (UNVERIFIED). Operations that cannot be reversed, such as
  227. file output, are not undone by any of them and do not get a second confirmation
  228. yet (planned). The panel's Plans list shows pending plans only; `aec-model-bridge-approve show <plan_id>`
  229. works for a plan in any state, while `proofs/` bundles exist only for plans that
  230. were executed (or attempted). The lifecycle is in
  231. [ADR 0008](docs/0008-approval-gate-lifecycle.md).
  232. For unattended pipelines you can set `MCP_REVIT_APPROVAL_MODE=auto`. That turns
  233. the human check off, so use it only in a controlled environment.
  234. ## Supported Revit versions
  235. | Revit version | Add-in target | Build tools |
  236. |---|---|---|
  237. | 2024 | .NET Framework 4.8 | .NET 8 SDK and .NET Framework 4.8 developer pack |
  238. | 2025 | .NET 8 for Windows | .NET 8 SDK |
  239. | 2026 | .NET 8 for Windows | .NET 8 SDK |
  240. | 2027 | .NET 10 for Windows | .NET 10 SDK |
  241. These are the build targets. CI compiles the add-in for all four years, but no
  242. year has been verified in a live Revit session yet.
  243. You also need Windows 10 or 11, Python 3.11 or later, and a licensed Revit
  244. installation for the version you use. Mock mode runs the server without Revit,
  245. which is useful for development and tests.
  246. ### Other integrations
  247. | Integration | Status |
  248. |---|---|
  249. | Revit | Available. Native C# add-in. |
  250. | IFC (IfcOpenShell) | Available. Reads IFC files without Revit running. |
  251. | Rhino and Grasshopper | Available. Connects to the Rhino add-in on `localhost:3004`. |
  252. | Speckle | Available. Needs a Speckle client ID in your environment. |
  253. | Navisworks Manage | In progress. The provider and its tools are registered. The Navisworks add-in is not finished. |
  254. | Power BI | In progress. The provider and tool exist but are not registered in the hub. |
  255. | Excel, Parquet and DuckDB | Planned. |
  256. Product names and logos belong to their owners. The banner uses them only to show what this project works with.
  257. ## Install the Revit add-in
  258. **Easiest (Windows):** download `AECModelBridge-Setup-<version>.exe` from the [latest release](https://github.com/Sam-AEC/aec-model-bridge/releases/latest), double-click it, pick your Revit versions and restart Revit. It installs the add-in and the bundled Python server. If you tick the box, it also sets up Claude Desktop and VS Code, and it backs up your current settings first. Uninstall it from Windows Settings. The steps below are for building from source.
  259. You install two parts: the Python MCP server and the Revit add-in. Live Revit
  260. automation needs both.
  261. ### 1. Install the MCP server
  262. ```powershell
  263. git clone https://github.com/Sam-AEC/aec-model-bridge.git
  264. cd aec-model-bridge
  265. py -m venv .venv
  266. .\.venv\Scripts\Activate.ps1
  267. python -m pip install -e packages/mcp-server-revit
  268. ```
  269. ### 2. Install the Revit add-in
  270. Set the version to match your Revit installation. If Windows blocks the
  271. downloaded scripts, right-click each `.ps1` file, open Properties, and select
  272. Unblock before running them.
  273. ```powershell
  274. $RevitVersion = Read-Host "Revit year (2024, 2025, 2026, or 2027)"
  275. .\scripts\package.ps1 -RevitVersion $RevitVersion
  276. .\scripts\install.ps1 -RevitVersion $RevitVersion
  277. ```
  278. The installer places version-specific binaries in:
  279. ```text
  280. C:\ProgramData\AECModelBridge\bin\<year>
  281. ```
  282. The add-in manifest is installed per user in:
  283. ```text
  284. %APPDATA%\Autodesk\Revit\Addins\<year>
  285. ```
  286. Use `-AllUsers` with `install.ps1` to install the manifest under
  287. `C:\ProgramData\Autodesk\Revit\Addins\<year>` instead.
  288. To prepare binaries for every supported version in one pass:
  289. ```powershell
  290. .\scripts\package.ps1 -RevitVersion All
  291. ```
  292. Each [GitHub release](https://github.com/Sam-AEC/aec-model-bridge/releases/latest)
  293. has a ready-made package per Revit year, for example
  294. `aec-model-bridge-revit-2026-<version>.zip`. Unzip it and run
  295. `.\install.ps1 -RevitVersion 2026` instead of building from source. For a double-click
  296. Windows installer, `scripts/build-installer.ps1` builds one with Inno Setup.
  297. The full guide, with troubleshooting, is in [docs/install.md](docs/install.md).
  298. ## Connect Claude Desktop to Revit
  299. Add the server to your MCP client configuration. For Claude Desktop, that is
  300. the `mcpServers` section of `claude_desktop_config.json`. Codex, Cursor, VS
  301. Code and other MCP clients use the same `command`, `args` and `env` values in
  302. their own config format.
  303. Use the Python executable from your virtual environment, and choose a workspace
  304. folder the server may access:
  305. ```json
  306. {
  307. "mcpServers": {
  308. "aec-model-bridge": {
  309. "command": "C:\\path\\to\\aec-model-bridge\\.venv\\Scripts\\python.exe",
  310. "args": ["-m", "revit_mcp_server.mcp_server"],
  311. "env": {
  312. "MCP_REVIT_MODE": "bridge",
  313. "MCP_REVIT_WORKSPACE_DIR": "C:\\RevitProjects",
  314. "MCP_REVIT_ALLOWED_DIRECTORIES": "C:\\RevitProjects"
  315. }
  316. },
  317. "aec-model-bridge-revit-2026": {
  318. "command": "C:\\path\\to\\aec-model-bridge\\.venv\\Scripts\\python.exe",
  319. "args": ["-m", "revit_mcp_server.mcp_server"],
  320. "env": {
  321. "MCP_REVIT_MODE": "bridge",
  322. "MCP_REVIT_HOST_VERSION": "2026",
  323. "MCP_REVIT_WORKSPACE_DIR": "C:\\RevitProjects",
  324. "MCP_REVIT_ALLOWED_DIRECTORIES": "C:\\RevitProjects"
  325. }
  326. }
  327. }
  328. }
  329. ```
  330. Leave out `MCP_REVIT_HOST_VERSION` to target the newest open Revit instance.
  331. Set it to a year such as `2024` or `2026` to lock a client entry to that Revit
  332. version. `MCP_REVIT_BRIDGE_URL` overrides the endpoint for advanced setups.
  333. VS Code users can start from [`.vscode/mcp.json`](.vscode/mcp.json). Hermes
  334. Desktop users can start from [`docs/examples/hermes-desktop.json`](docs/examples/hermes-desktop.json) after replacing the
  335. placeholder Python path. Clients that support MCP Bundles can install the
  336. `.mcpb` file from the
  337. [latest release](https://github.com/Sam-AEC/aec-model-bridge/releases/latest).
  338. The Revit add-in is still required, because the server talks to the running
  339. desktop application.
  340. ### Check the connection
  341. Restart Revit after installing the add-in, open a model, and run:
  342. ```powershell
  343. $registry = Get-ChildItem "$env:LOCALAPPDATA\AECModelBridge\registry\revit-*.json" | Select-Object -First 1
  344. $switch = Get-Content $registry.FullName -Raw | ConvertFrom-Json
  345. Invoke-RestMethod "$($switch.endpoint)/health"
  346. ```
  347. The response should report `healthy` and the running Revit version. In Revit,
  348. look for the `AEC Bridge` ribbon tab. Its Workflows panel has Open Panel,
  349. Health Check, Pending Actions and Reports. Its Tools panel has Config, Help
  350. and About.
  351. ## Security
  352. - The Revit bridge listens on localhost only.
  353. - The server reads and writes only inside the folders in
  354. `MCP_REVIT_ALLOWED_DIRECTORIES`.
  355. - Mutating tools need an approved plan unless you turn approval off, and
  356. `look_only` mode refuses them outright.
  357. - Approval is recorded with the channel (panel or command line) and your
  358. operating-system account. It does not prove who is typing, so do not give an
  359. AI client a shell on the account you approve plans with.
  360. - Tool calls are written to an audit log, and secrets are redacted.
  361. Details are in [docs/security.md](docs/security.md). To report a
  362. vulnerability, follow [SECURITY.md](SECURITY.md).
  363. ## FAQ
  364. ### What is an MCP server for Revit?
  365. The Model Context Protocol (MCP) is an open standard that lets AI assistants
  366. call tools in other software. An MCP server for Revit publishes Revit
  367. operations as tools. The assistant picks the tools, and the add-in runs them
  368. inside Revit.
  369. ### Which AI assistants work with it?
  370. Any MCP client that can start a local stdio server. Setup is documented for
  371. Claude Desktop, VS Code with GitHub Copilot, Cursor and Codex, and for clients
  372. that read a standard `mcpServers` configuration. Windsurf, Cline, Roo Code,
  373. Continue, Zed, Claude Code and Gemini CLI should work the same way but have not
  374. been tested. See [compatibility](docs/compatibility.md). The panel chat can also
  375. use an Anthropic API key, or the `claude` or `codex` command-line tools if they
  376. are installed. See [ADR 0012](docs/0012-native-agent-chat-backend.md).
  377. ### Can the AI change my model without asking?
  378. Not in the default mode. Tools that change the model are blocked until a plan
  379. is approved by a person, in the Revit panel or with the
  380. `aec-model-bridge-approve` command. Read-only tools run without approval. In
  381. `look_only` mode nothing that changes the model runs at all. If you set
  382. `MCP_REVIT_APPROVAL_MODE=auto`, approval is skipped.
  383. ### Does it send my model to the cloud?
  384. The server and the add-in run on your machine, and the bridge listens on
  385. localhost. The AI assistant sees what the tools return, and those results go
  386. to the model provider behind your client. Cloud providers, such as Speckle,
  387. only run when you configure them and call their tools.
  388. ### Does it work with IFC files without Revit?
  389. Yes. The IFC provider reads files with IfcOpenShell. It can return file
  390. metadata, the spatial structure, element properties and bounding boxes, run
  391. queries by class, GUID, name or property, and validate the schema. It does
  392. not edit IFC files.
  393. ### Can I use it without Revit installed?
  394. Only in mock mode, which is meant for development and tests. Live model work
  395. needs Revit 2024 to 2027 and the add-in.
  396. ## Releases and versions
  397. AEC Model Bridge follows Semantic Versioning. Releases are tagged `vX.Y.Z` on
  398. GitHub, and a root `VERSION` file holds the version number. See
  399. [docs/versioning.md](docs/versioning.md) for the release process and
  400. [CHANGELOG.md](CHANGELOG.md) for what changed in each version.
  401. ## Development
  402. ```powershell
  403. # Python tests
  404. python -m pytest packages/mcp-server-revit/tests
  405. # Build one Revit version, for example 2026
  406. .\scripts\build-addin.ps1 -RevitVersion 2026 -Configuration Release
  407. # Build all supported versions
  408. .\scripts\package.ps1 -RevitVersion All
  409. ```
  410. CI builds the Python server and the add-in targets for Revit 2024 through 2027.
  411. See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.
  412. ## Documentation
  413. - [Installation guide](docs/install.md)
  414. - [Tool reference](docs/tools-generated.md)
  415. - [Architecture](docs/0001-multi-provider-architecture.md)
  416. - [Configuration reference](docs/configuration-reference.md)
  417. - [Security](docs/security.md)
  418. - [MCP clients and registry](docs/marketplaces.md)
  419. - [Versioning and releases](docs/versioning.md)
  420. - [Release checklist](docs/release-checklist.md)
  421. - [First check after install](docs/first-check.md)
  422. - [Demo runbook](docs/demo-runbook.md)
  423. - [Proof bundles and revert plans](docs/proof-and-revert.md)
  424. - [Privacy](docs/privacy.md)
  425. - [Roadmap](docs/roadmap.md)
  426. - [All documentation](docs/README.md)
  427. - [Contributing](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md)
  428. - [Contributors](CONTRIBUTORS.md)
  429. ## Built with
  430. AEC Model Bridge stands on open-source work. It is independent and is not affiliated with or endorsed by any project named here.
  431. - [Model Context Protocol](https://modelcontextprotocol.io) Python SDK (MIT) for the MCP server
  432. - [IfcOpenShell](https://ifcopenshell.org) (LGPL-3.0-or-later) for IFC files
  433. - [specklepy](https://github.com/specklesystems/specklepy) (Apache-2.0) for Speckle
  434. - [pydantic](https://docs.pydantic.dev), [httpx](https://www.python-httpx.org), [NetworkX](https://networkx.org), [openpyxl](https://openpyxl.readthedocs.io) and [PyYAML](https://pyyaml.org) (MIT or BSD)
  435. - [Anthropic Python SDK](https://github.com/anthropics/anthropic-sdk-python) (MIT) for the built-in agent chat
  436. - [Serilog](https://serilog.net), [IronPython](https://ironpython.net) and [Microsoft WebView2](https://developer.microsoft.com/microsoft-edge/webview2/) in the Revit add-in
  437. - Autodesk Revit and Navisworks and McNeel Rhino are separate products that you license yourself. This project does not include their code.
  438. Licence texts and the full list of packages are in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). Licences were read from package metadata; rows that could not be verified are marked as such.
  439. ## Project and license
  440. Maintained by [A. Sam Mohammad](https://github.com/Sam-AEC).
  441. [LinkedIn](https://www.linkedin.com/in/a-sam-mohammad-92790416b) |
  442. [Issues](https://github.com/Sam-AEC/aec-model-bridge/issues)
  443. [GPL-3.0-or-later with the Revit Linking Exception, or a commercial license](LICENSING.md).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.