Horizun Revit MCP — an MCP server for Autodesk Revit

Point Claude — or Codex, Cursor, Cline, Windsurf, any MCP client — at a running Autodesk 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, so a silent rollback becomes an error instead of a false success, and counts come from reading the model again rather than from calls that did not throw. Free and open source, Apache-2.0. Part of the Horizun Hub ecosystem.

What this is. The bridge: transport, safety guards and a generic tool surface over the Revit API, for Revit 2023 through 2027. 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, audit criteria and reporting that turn these commands into delivery workflows live in Horizun Hub. This repository is the socket; the Hub is what plugs into it.

What you can ask it

Ordinary language on the left; what the bridge actually does on the right. None of it is scripted in advance — the client picks the tools.

Ninety per cent of the design is in the "no". A slab whose hosted families cannot be put back rolls back alone; a clash count of zero is a zero you can trust; an ambiguous request is refused with a reason instead of resolved by guessing.

// horizun_health, abbreviated
{
  "status": "healthy",
  "horizun_version": "1.0.0",
  "horizun_commit": "ced1aa1",
  "built_from_clean_tree": true,
  "revit_version": "2026",
  "revit_build": "20250406_1515(x64)",
  "no_active_document": false,
  "active_document": { "title": "TORRE-A-EST.rvt", "is_workshared": true },
  "open_document_count": 3
}

Install

Windows, at least one Revit 2023–2027, and Revit closed. Everything else the installer checks for you, and it changes nothing when it refuses.

1 · Get the installer and verify it

Download horizun-mcp-<version>-setup.exe and SHA256SUMS.txt from the latest release, then check the hash before running anything:

Get-FileHash .\horizun-mcp-<version>-setup.exe -Algorithm SHA256
Select-String -Path .\SHA256SUMS.txt -Pattern 'setup.exe'

Every installable release carries a payload manifest.json, package-hashes.json and an SBOM. Stable releases also carry one live verification report per supported Revit year.

Read this before you run it. Horizun Windows releases are intentionally unsigned. SHA-256, the payload manifest, SBOM and build-provenance attestation verify the released bytes; they do not authenticate a Windows publisher. The bootstrap therefore requires the explicit -AllowUnsigned acknowledgement shown below, and Windows/Revit may show an unknown-publisher warning. Invalid or self-signed public artifacts are refused. See the unsigned release policy.

If you would rather have the script do the same checks, one paste verifies the complete SHA-256 against that same GitHub release, installs quietly and finishes client registration:

$s = irm https://raw.githubusercontent.com/HorizunGroup/horizun-revit-mcp/main/install-release.ps1; & ([scriptblock]::Create($s)) -AllowUnsigned

Download it first and pass -Version <tag> to pin a release, or -Interactive for the Setup wizard. Quiet, latest and automatic client completion are the defaults.

2 · Let it configure your MCP client

The same Setup serves every supported client and every client runs the same installed horizun-mcp.exe:

The installer waits for Claude Code or Codex to close before editing their configuration, makes timestamped backups, preserves every other MCP entry, and verifies what it wrote. Durable status lives in %LOCALAPPDATA%\Horizun\install-status.json. See the exact per-client procedure in docs/CLIENTS.md.

# after closing Claude Code — user scope makes it available across projects
claude mcp add --scope user horizun-revit -- "C:\Users\<YOU>\AppData\Local\Programs\Horizun\MCP\server\horizun-mcp.exe"

# after closing Codex
codex mcp add horizun-revit -- "C:\Users\<YOU>\AppData\Local\Programs\Horizun\MCP\server\horizun-mcp.exe"

# Codex timeouts — %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

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

pwsh -File scripts/install-claude-desktop-extension.ps1   # a real .mcpb Desktop Extension
pwsh -File scripts/diagnose-integrations.ps1              # Codex, Claude Code, Claude Desktop and ChatGPT Work

3 · Start Revit and check

Two things to expect on the first start, neither of them a fault:

• Revit can show a Security dialog when the publisher is not already trusted — after verifying the build, choose Always Load. It can open on a monitor you are not looking at: a Revit that seems stuck on startup with the CPU idle is often this dialog hiding.
• With a document open, a Horizun Hub tab appears in the ribbon. Its Estado del puente button answers "is this working, and which version?" without leaving Revit.

From your MCP client, horizun_health answers the same with the commit included. A contract hash mismatch means one half is on an older build: close Revit and install again.

Build from source instead

Nothing prebuilt is downloaded or run: everything is compiled on your machine against the Revit already installed. You need the .NET SDK 10.0.400, fixed by global.json so release bytes do not depend on the latest installed patch. The produced add-ins still target the runtime hosted by each Revit year: .NET Framework 4.8 for 2023–2024, .NET 8 for 2025–2026 and .NET 10 for 2027.

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

It finds every Revit 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 — stamped commit plus SHA-256 against what was staged. A build failure changes nothing; a failure after that rolls back through its undo ledger and tells you the exact state you are in. To update: git pull, close Revit, run it again.

Or hand the whole thing to an agent — paste this into Claude Code or Codex in any folder:

Clone https://github.com/HorizunGroup/horizun-revit-mcp into this folder, read its
AGENTS.md, and follow the install procedure there. Install and verify the binaries,
then confirm the automatic completion status. Do not edit an active client's
configuration; let the installed helper finish registration after that client exits.

Both pick up AGENTS.md automatically once they are inside the repository. It carries the prerequisites, the failure modes and the two surprises worth knowing before the first Revit start.

Architecture

• Horizun.Revit — the add-in. App (IExternalApplication) starts a named-pipe server and publishes a discovery file; Dispatcher crosses each request onto Revit's UI thread via ExternalEvent; Guard and Reconcile are the "cannot lie" commit contract; commands live under Commands/.
• Horizun.Server — the MCP server. The wire format is hand-rolled from the open MCP spec, with no third-party SDK: it discovers the pipe, speaks MCP over stdio and forwards to the plugin. Schemas and behavioural effects live in one shared contract, so tools/list answers with Revit closed without drifting from the add-in. It negotiates MCP through 2025-11-25; exposes standard Tools, Resources, Prompts, Completions, opt-in Logging and durable Tasks; and returns both backward-compatible text and structuredContent. Five tools are host-resident — they answer inside the server and never touch Revit.
• One command at a time. Concurrent calls wait in a bounded 16-slot FIFO queue; a full queue applies explicit backpressure instead of dropping work. Every reply carries what Revit raised while the command ran — warnings, errors and modal dialogs — on success and on failure.

Capabilities

Grouped by what you would actually be doing. The complete reference — every tool, and what each one refuses — is in docs/TOOLS.md.

# Option A: short-lived OAuth access token
$env:HORIZUN_POWER_BI_ACCESS_TOKEN = '<token with Dataset.ReadWrite.All>'

# Option B: Entra service principal; Horizun obtains the access token
$env:HORIZUN_POWER_BI_TENANT_ID = '<tenant-guid>'
$env:HORIZUN_POWER_BI_CLIENT_ID = '<application-guid>'
$env:HORIZUN_POWER_BI_CLIENT_SECRET = '<secret>'

Status and evidence

Working and in production use. Stable promotion is governed by published, release-scoped evidence rather than by a local success claim.

• Revit-free suites are enforced in CI, and only those. A hosted runner has no RevitAPI.dll, so building the add-in there would be a lie; the Revit-bound half is verified live with scripts/verify-live.ps1 and published per release. A skipped job that says why is worth more than a green tick that covered less than it appeared to.
• Built for five Revit years — 2023 through 2027, each compiled against its own API. The server and the add-in hash one shared contract and ship together; there is no partial deployment.
• Live evidence is release-scoped. Stable promotion requires a published report for every supported year. If an artifact is absent, local experience or a compiled DLL is not substituted for it. See the release policy.
• Known limits, stated: excel_write_rows appends below an Excel Table without expanding the table's range (reported per call); a catalog that is neither UTF-8 nor Latin-1 is decoded as Latin-1 and says so; cancelling a request prevents it only while it is still queued — once Revit starts the command, cancellation stops you waiting but cannot interrupt the Revit API on its UI thread. General creation of in-place families is not available in the public Revit API, so Horizun creates loadable RFA families and project-resident system types instead of driving the modal family editor by UI automation.

The public comparison is task-based rather than tool-count based: a feature scores only when its schema is typed, invalid input is refused before mutation, and the claimed result is measured after the operation. Cases, scoring rules and current results are in docs/BENCHMARK.md.

dotnet build src/Horizun.Revit -c Release -p:RevitYear=2026   # one year at a time
dotnet build src/Horizun.Server -c Release                    # the MCP server (Revit-free)
dotnet test tests/Horizun.Core.Tests
dotnet test tests/Horizun.Server.Tests
pwsh scripts/verify-live.ps1 -Year 2026 -OldFile <a model saved in another Revit>

Security

horizun_execute_python runs arbitrary Python inside Revit with the rights of the signed-in user, and it is disabled by default. A fresh install reads as permission_profile: "safe_write": verified typed edits inside the active model are available, while arbitrary code, document-session changes and external writes require an explicit owner decision.

An explicit choice in %USERPROFILE%\.horizun\settings.json is always respected — read_only, safe_write, full_write or enable_execute_python: false keep arbitrary code off, allowed_tools and denied_tools narrow any profile, and a settings file that exists but cannot be parsed falls closed (read_only, Python off) so a corrupted restriction never reads as consent. A client may call horizun_request_python_access to put the question visibly in Revit, but it cannot answer it. The machine owner can use the Python ON/OFF button to grant persistent access until that same user revokes it; pressing it again revokes the permission immediately. scripts/enable-execute-python.ps1 remains the explicit administrative path and reverts with -Disable. The server emits notifications/tools/list_changed when the effective permission changes, so compatible clients update automatically; clients that ignore the notification need one restart.

There is no inbound network listener: named pipes are not reachable across a network, and the server speaks stdio to whatever launched it. The optional horizun_power_bi_push makes bounded outbound HTTPS calls only to fixed Microsoft Entra and api.powerbi.com endpoints, and accepts no URL or credential in tool arguments. There is no telemetry and no maintainer-operated data collection.

The full threat model — what is defended, and what deliberately is not — is in docs/security-model.md, and it is written to be argued with. Local state and user-requested network operations are described in the privacy policy. To report a vulnerability, see SECURITY.md. The exact line between source-candidate evidence and external certification is maintained in production readiness.

Horizun Hub

Horizun Hub is the product ecosystem this bridge belongs to: PowerBIM Exporter for Revit and Civil 3D, PowerBIM Online, BuildMotion, CopyToExcel and Family Browser; PowerBIM + AI training; 4D/5D quantification templates; Power BI dashboards and .pbit templates; agents and MCP workflows for standardising families and auditing models; and APS extraction into Power BI.

The MCP stays organisation-neutral: company standards, catalogues and audit rules are supplied by those workflows or by the caller, never compiled into the bridge. docs/HORIZUN-HUB.md draws the full line between the open-source gateway and the Hub.

Contributing

Issues and pull requests are welcome — bug reports, Revit-year compatibility findings and capability proposals each have a form. Start with CONTRIBUTING.md and the code of conduct; AGENTS.md is the machine-readable version of the same rules, and llms.txt is the discovery summary for indexers and AI systems.

License

Apache License 2.0 — see LICENSE and NOTICE. Third-party components remain under their own licenses, listed with versions in THIRD-PARTY-NOTICES.md.

The Autodesk Revit API is referenced at build time and never redistributed. Revit, Autodesk and Autodesk Docs are trademarks of Autodesk, Inc. This project is not affiliated with, endorsed by, or sponsored by Autodesk, Inc.