rvt-mcp

<!-- mcp-name: io.github.bimwright/rvt-mcp -->

<p align="center">
  <img src="https://raw.githubusercontent.com/bimwright/.github/master/assets/logos/rvt-mcp.png" alt="rvt-mcp" width="180" />
</p>

<h1 align="center">rvt-mcp</h1>

<p align="center">
  MCP gateway for Autodesk Revit — local tools for agents, optional personal bake loop
</p>

<p align="center">
  <a href="https://github.com/bimwright/rvt-mcp/actions/workflows/build.yml"><img src="https://github.com/bimwright/rvt-mcp/actions/workflows/build.yml/badge.svg" alt="build" /></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="license" /></a>
  <a href="#supported-revit-versions"><img src="https://img.shields.io/badge/Revit-2022--2027-186BFF" alt="Revit 2022-2027" /></a>
  <a href="#tools"><img src="https://img.shields.io/badge/MCP-229%20tools-6C47FF" alt="MCP tools" /></a>
</p>

<p align="center">
  English · <a href="README.vi.md">Tiếng Việt</a> · <a href="README.zh-CN.md">简体中文</a> · <a href="README.ja.md">日本語</a>
</p>

---

## Install

Client machines should use the setup ZIP from [GitHub Releases](https://github.com/bimwright/rvt-mcp/releases/latest). It bundles a self-contained MCP server and Revit 2022–2027 plugins — no .NET SDK, NuGet global tool, or source clone.

**AI agents:** download `RvtMcp.Setup-*-win-x64.zip` from the latest release and run the installer. Do **not** clone, build, or `dotnet tool install` unless the user asked for a developer setup. Protocol: [AGENTS.md](AGENTS.md).

```powershell
$tag = (Invoke-RestMethod https://api.github.com/repos/bimwright/rvt-mcp/releases/latest).tag_name
$zip = "$env:TEMP\RvtMcp.Setup-$tag-win-x64.zip"
$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 $zip
Expand-Archive $zip -DestinationPath $dir -Force

powershell -ExecutionPolicy Bypass -File "$dir\install.ps1" -WhatIf
powershell -ExecutionPolicy Bypass -File "$dir\install.ps1"
```

The installer detects Revit 2022–2027, installs matching plugins, copies the server under `%LOCALAPPDATA%\RvtMcp\rvt\server\<version>\`, and wires detected MCP clients. Override with `-Client codex|opencode|claude|kilo|none`.

Do **not** install v0.5.0 or earlier ZIPs. Do **not** `dotnet tool install -g Bimwright.Rvt.Server` (legacy 0.1–0.3). Do **not** use NuGet instead of this ZIP on a Revit client machine — the tool package has no add-in.

For AutoCAD, use [dwg-mcp](https://github.com/bimwright/dwg-mcp) separately — different product, different install.

### Check that it works

1. Open Revit with a model.
2. Start the MCP connection from the ribbon (BIMwright / RvtMcp panel).
3. From the MCP client, list tools, then call `revit_get_current_view_info`.

You should get something like:

```json
{ "viewName": "Level 1", "viewType": "FloorPlan", "levelName": "Level 1", "scale": 100 }
```

If that fails, install is not done yet — fix client config / plugin load before anything else.

### Upgrade an existing installation

Updates are manual. Close all Revit windows and stop the MCP connection in your AI client, extract the new release ZIP into a separate folder, then run its `install.ps1 -WhatIf` followed by `install.ps1`. Upgrade the server and plugins together; restart Revit and the MCP client, then repeat the checks above. Do not uninstall first: the full uninstaller also removes personal ToolBaker data and logs.

The **unreleased installer in this source tree** preserves existing `rvt-mcp` arguments, environment, enabled/disabled state and other options while updating the executable path. It leaves other entries (including legacy aliases) intact. Custom launcher wrappers and unsupported TOML layouts require `-Client none` plus a manual path update; project-level configs are not scanned. These protections are not in the published v0.6.1 installer.

Before replacing files, the new installer checks package checksums when a manifest is present, validates every selected plugin ZIP, stages the payload and refuses installation while Revit is running. Caught installation errors restore earlier plugin/server/config changes. Config backups use `<config>.rvtmcp.bak`. If rollback is blocked by file locks or permissions, the error identifies retained `.rvtmcp-rollback-*` backups; hard termination or power loss requires manual recovery. See [installer verification](docs/testing/installer-upgrade/README.md).

### Uninstall

From the setup ZIP root (or this repo’s `scripts/`):

```powershell
# Setup ZIP layout:
powershell -ExecutionPolicy Bypass -File .\uninstall.ps1 -WhatIf
powershell -ExecutionPolicy Bypass -File .\uninstall.ps1 -Yes

# Clone layout:
powershell -ExecutionPolicy Bypass -File .\scripts\uninstall-all.ps1 -WhatIf
powershell -ExecutionPolicy Bypass -File .\scripts\uninstall-all.ps1 -Yes
```

Removes plugins, self-contained server, client entries, discovery files, logs, and ToolBaker cache.

### Developer install

```powershell
git clone https://github.com/bimwright/rvt-mcp.git
cd rvt-mcp
dotnet build src/RvtMcp.sln -c Debug
powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1 -SourceDir . -Client none
```

Close every Revit first — the build deploys plugin DLLs into `%APPDATA%\Autodesk\Revit\Addins\<year>\RvtMcp\`. `install.ps1` finds Revit 2022–2027, copies the server under `%LOCALAPPDATA%\RvtMcp\rvt\server\<version>\`, and wires detected MCP clients (`-Client codex|opencode|claude|kilo|none`, `-Years 2024` for one year).

**Optional — NuGet server only** (does **not** install Revit plugins). Use this if the add-in is already on the machine (ZIP or a local build) and you want the MCP server on PATH:

```powershell
dotnet tool uninstall -g Bimwright.Rvt.Server   # skip if you never installed the 0.1–0.3 tool
dotnet tool install -g RvtMcp.Server --version 0.6.1
```

Command name: `rvt-mcp`. Keep using the GitHub Release ZIP for plugins. `Bimwright.Rvt.Server` is obsolete.

### Migrating from `Bimwright.Rvt.*` (v0.3 and earlier)

v0.4+ renamed packages and folders to `RvtMcp.*` (repo name and brand stay bimwright).

1. Close every Revit.
2. `pwsh scripts/uninstall-old.ps1` — drops old `%APPDATA%\…\Bimwright\` plugins and old server root; keeps user bake/journal data and migrates it to `%LOCALAPPDATA%\RvtMcp\` on first new launch.
3. Install the current GitHub Release ZIP (Client install above). Do not install v0.5.0 or earlier packages. Uninstall the old global tool if present: `dotnet tool uninstall -g Bimwright.Rvt.Server`.
4. Point MCP clients at entry name **`rvt-mcp`** (old per-year `bimwright-rvt-r22`… entries are removed by the installer).

---

## What this is

`rvt-mcp` is a **local** bridge between an MCP client (Claude, Cursor, Codex, OpenCode, …) and a running Revit session.

Two processes:

| Piece | Role |
|--------|------|
| **RvtMcp.Server** | .NET 8 MCP server on stdio. No Revit reference — builds anywhere. |
| **RvtMcp.Plugin** | One thin add-in per Revit year (2022–2027). Runs inside Revit, executes on the UI thread. |

Agent → MCP → server → localhost TCP (≤2024) or Named Pipe (≥2025) → plugin → Revit API.

Everything stays on the machine. No cloud relay is required for the gateway itself.

There is no Node/TypeScript sidecar. Server, plugins, handlers, and ToolBaker are C# end to end. Shared command code lives in `src/shared/`; each year is a small shell project with `#if` where the API drifted. Details: [ARCHITECTURE.md](ARCHITECTURE.md).

---

## Why it exists

People who live in Revit already know what they want automated. The friction was always shipping that idea as software: learn enough C#/Dynamo, fight the API, package an add-in, survive version upgrades — or pay someone else, or buy a fixed tool that only half-matches the office.

Agents change the first half of that loop (describe the task, try it live). They do not remove transactions, units, selection, worksharing, or “did this just trash the model?” That is what this gateway is for: a **typed tool surface** for common work, plus an escape hatch when you need ad-hoc C# inside Revit, plus an **optional** path to turn repeated local patterns into personal tools (ToolBaker).

It is not a universal add-in for every firm. Offices differ. The bet is: start from a shared runtime, grow *your* tools on top.

**Scope posture (honest):** we do not mint a new MCP tool for every edge case. Prefer typed tools when they exist; for everything else use `revit_send_code_to_revit` (C# only). Family *project* management is covered; full Family Editor authoring suites and Revit Viewer hosts are out of scope for now — see [docs/roadmap.md](docs/roadmap.md).

---

## How a normal session looks

1. Revit open with a model; plugin connected (ribbon).
2. MCP client starts `rvt-mcp` / the installed server.
3. Agent uses tools: query view/selection, create grids/rooms, sheets, MEP, export, … Lengths in **mm** at the tool boundary.
4. Several writes in one undo step: `revit_batch_execute`.
5. Multiple Revits running: `revit_list_available_targets` then `revit_switch_target` with a four-digit year (`2024`, not `R24`).

When no typed tool fits:

```text
revit_send_code_to_revit   # C# body, compiled and run inside the plugin
```

That tool is on by default (toolset `meta`). Strip it with `--read-only` or `--disable-toolbaker` if you do not want agents compiling code in the model.

The source checkout also supports a C# body with helper type declarations and an opt-in failure preprocessor; these additions are not in the published v0.6.1 plugin. See [send-code source forms and failure handling](docs/send-code.md). Upgrade the server and plugin together so tool descriptions match the loaded runtime.

For stairs, use the [conversation and send-code workflow](docs/stairs-workflow.md): tested scripts plus sample questions to resolve layout, dimensions, and railing intent before adapting the code. A dedicated `create_stairs` tool is deferred.

### ToolBak