horizun-revit-mcp

# Horizun Revit MCP — Model Context Protocol server for Autodesk Revit

Open-source **Model Context Protocol (MCP) server for Autodesk Revit**. Horizun
connects Codex, Claude, Cursor and other MCP clients to a running Revit session
for typed BIM queries, verified model edits, family authoring, exports and Power
BI workflows. **Free and open source, Apache-2.0.** Part of the [Horizun
Hub](https://horizunhub.com) ecosystem.

> **Official stable release: v0.5.0.** This is the public source repository for
> Horizun Revit MCP. It contains the complete implementation, typed Revit
> operations, tests, installation scripts, security model and benchmark evidence.

## Why Horizun is built to lead the Revit MCP benchmark

Horizun is measured by verified outcomes, not by a raw count of tool names:

| Differentiator | What the public source proves |
|---|---|
| Native Revit coverage | Typed creation and editing for architecture, structure, MEP, views, sheets, schedules, families and system-family types. |
| Family authoring | RFT → RFA compilation with parameters, formulas, types, reference planes, labeled dimensions, symbolic/model lines, nested point instances, solid/void forms and MEP connectors. |
| Interoperability | Verified PDF, DWG, IFC, Navisworks NWC, multi-view FBX, image and schedule export, plus direct Power BI push ingestion. |
| Reliability | Dry-run plans, single-use confirmations, durable idempotency, bounded queueing, one Revit API operation at a time and post-commit re-reads. |
| Federated models | Host and loaded-link inventory, queries, quantities, clashes and schedules with source-model identity and explicit coverage. |
| Honest failure modes | Unsupported or ambiguous inputs are refused with a reason; the bridge never reports success from a call that merely did not throw. |

The benchmark is reproducible from [`docs/BENCHMARK.md`](docs/BENCHMARK.md).
Public CI passes **292 core tests + 162 server tests**, builds the MCP server with
warnings treated as errors, audits NuGet dependencies and runs the repository-safe
part of the sensitive-data scan. Revit-dependent CI jobs require a private
self-hosted runner and are reported as skipped when it is unavailable. The
benchmark marks every capability whose current public evidence is still pending
a live Revit or Power BI fixture; a green hosted-CI check is never presented as
proof that those live operations ran.

The server metadata is also prepared for the [Official MCP Registry](https://registry.modelcontextprotocol.io/)
under `io.github.HorizunGroup/horizun-revit-mcp`, and the repository publishes a
machine-readable [llms.txt](llms.txt) discovery summary for AI systems and
indexers.

## Horizun Hub: the ecosystem around the MCP

[Horizun Hub](https://horizunhub.com) is the product ecosystem from Horizun
Group. Horizun Revit MCP is its open-source automation and Revit API layer; the
Hub adds the training, apps, data products and expert workflows that turn the
bridge into a complete BIM operating system:

- **Apps:** PowerBIM Exporter for Revit, PowerBIM Online, PowerBIM Exporter for
  Civil 3D, BuildMotion, CopyToExcel and Family Browser.
- **Academia:** PowerBIM + IA training and the growing course library.
- **Quantification and 4D/5D:** Revit + Navisworks examples, templates and
  construction-planning workflows.
- **Power BI and content:** dashboards, `.pbit` templates, visual assets and
  data workflows.
- **IA and automation:** agents, MCP workflows and scripts for standardising
  families and auditing models.
- **APS connection:** extraction of Autodesk Construction Cloud data into Power
  BI workflows.
- **Expert support:** two hours per month with a Horizun Group BIM expert,
  delivered through Zoom or Teams.
- **Learning media:** BIM Para Todos videos and tutorials covering Revit,
  Power BI, Speckle, Civil 3D and AI.

The MCP remains organisation-neutral: company standards, catalogues and audit
rules are supplied by the Hub workflows or by the caller, rather than compiled
into the bridge. See [`docs/HORIZUN-HUB.md`](docs/HORIZUN-HUB.md) for the full
relationship between the open-source gateway and the Hub ecosystem.

Point Claude — or any MCP client — at a running Revit and let it read and write
the model, under one contract: **a command never reports work it did not
verify.** Every typed write is re-read from the model after the commit; a silent
rollback becomes an error, not a false success. Counts come from re-reading the
model, never from counting calls that did not throw. The deliberately low-level
`horizun_execute_python` escape hatch is the documented exception.

**What this is.** The bridge: transport, safety guards, and a generic tool
surface over the Revit API. Organisation-neutral by design — no company's
standards, catalogues or naming rules are compiled in; where a command needs
one, it is an input supplied at call time.

**What this is not.** A methodology. The standards, catalogues, audit criteria
and reporting that turn these commands into delivery workflows — model audits,
classification, family homologation, pre-delivery QA — live in
[Horizun Hub](https://horizunhub.com). This repository is the socket; the Hub
is what plugs into it.

## Install

### Install with an agent — recommended

Paste one of these into the agent you already have open, in any folder:

**Claude Code**

```
Clone https://github.com/HorizunGroup/horizun-revit-mcp into this folder, read its
CLAUDE.md, and follow the install procedure there. When it finishes, register the
MCP server with yourself using the exact path the installer printed, and tell me
which version and commit ended up installed.
```

**Codex**

```
Clone https://github.com/HorizunGroup/horizun-revit-mcp into this folder, read its
AGENTS.md, and follow the install procedure there. When it finishes, register the
MCP server with yourself using the exact path the installer printed, and tell me
which version and commit ended up installed.
```

Claude Code reads `CLAUDE.md` (which imports [AGENTS.md](AGENTS.md)); Codex reads
[AGENTS.md](AGENTS.md) directly. Either way the agent checks the prerequisites,
builds from this public source against each Revit version installed on the
machine, installs the matching add-in binaries and MCP server, verifies their
commit and SHA-256, and registers the resulting server path under the name
`horizun-revit` — so it reads as what it is next to every other MCP server on
your machine. Revit must be closed. No prebuilt executable is downloaded by this
path.

### Prebuilt release installer — optional

Download `horizun-mcp-<version>-setup.exe` from the
[latest release](https://github.com/HorizunGroup/horizun-revit-mcp/releases/latest),
close every Revit window, and run it. The installer detects Revit 2023–2027 and
deploys a different add-in binary compiled against each installed year's own API.
It also installs the MCP server and reports exactly which years succeeded. No Git
or .NET SDK is required for this path.

The release carries `SHA256SUMS.txt` and a complete payload manifest. The current
build is not signed by a publicly trusted code-signing CA, so Windows/Revit may
show a publisher warning; verify the SHA-256 before running it.

The setup installs every supported Revit payload present in the release and the
MCP server. It also installs Start-menu helpers to register or verify Horizun in
Codex and Claude. Registration is explicit and unchecked by default: the helper
makes timestamped backups, preserves all other MCP entries and refuses to edit a
client that is still running and could overwrite its configuration.

For a command-line installation without Git or an SDK, download the repository's
small bootstrap and let it select the latest release. It downloads the setup and
`SHA256SUMS.txt` from the same GitHub release, verifies the complete SHA-256, and
only then launches the installer:

```powershell
$p = Join-Path $env:TEMP 'horizun-install-release.ps1'
Invoke-WebRequest 'https://raw.githubusercontent.com/HorizunGroup/horizun-revit-mcp/main/install-release.ps1' -OutFile $p
powershell -ExecutionPolicy Bypass -File $p
```

Pass `-Version v0.5.0` to pin the official release instead of following `latest`.

### Build from source manually

This path builds everything from the repository, on your machine, against the
Revit already installed. **Nothing prebuilt is downloaded and run.**

**Prerequisites:** Windows, at least one Revit 2023–2027, the
[.NET SDK](https://dotnet.microsoft.com/download) (**8+** for Revit 2023–2026;
**10+** when building for Revit 2027), and **Revit closed** — the
installer refuses to run while Revit holds the add-in files, and changes nothing
when it refuses.

```powershell
git clone https://github.com/HorizunGroup/horizun-revit-mcp
cd horizun-revit-mcp
powershell -ExecutionPolicy Bypass -File .\install.ps1
```

It finds every Revit on the machine by its own `RevitAPI.dll`, builds the add-in
for each of those years and the MCP server, installs both, and reads every
installed binary back to prove it landed. A build failure changes nothing; a
failure after that rolls back and tells you the state you are in.

**The installer prints the exact path to register — use that one.** It is
already expanded for your machine, which matters: `%LOCALAPPDATA%` is expanded
by `cmd.exe` and **not** by PowerShell, so a config written with the variable
silently points nowhere.

```powershell
# Claude Code
claude mcp add horizun-revit -- "C:\Users\<YOU>\AppData\Local\Programs\Horizun\MCP\server\horizun-mcp.exe"
```

```toml
# Codex — %USERPROFILE%\.codex\config.toml
[mcp_servers.horizun-revit]
command = 'C:\Users\<YOU>\AppData\Local\Programs\Horizun\MCP\server\horizun-mcp.exe'
args = []
startup_timeout_sec = 120
tool_timeout_sec = 600
```

```json
// Cursor, Cline, Windsurf, Claude Desktop, and other MCP clients
{
  "mcpServers": {
    "horizun-revit": {
      "command": "C:\\Users\\<YOU>\\AppData\\Local\\Programs\\Horizun\\MCP\\server\\horizun-mcp.exe"
    }