Skip to main content
Glama
revit-bridge

revit-bridge

by revitbridge

revit-bridge

Intent bridge between designers and AI for Autodesk Revit: an MCP server that executes code in a running Revit, keeps a library of reusable capability packs, and refuses to run anything the designer has not confirmed - except a dry run, which is always rolled back and keeps nothing.

The package contains no model SDK, no vector store and no web framework. Your MCP host (Claude Desktop, Claude Code, any MCP client) brings the model; the revit-bridge-addin inside Revit executes the code.

Install

Prerequisites: Python 3.11+ with uv (for uvx), Revit 2020, 2021 or 2023-2026 with the add-in installed (one install per Revit year; see revit-bridge-addin) and its local TCP listener on (default 127.0.0.1:18080). dry_run_code, test_addin_command, zoom_view and capture_view need revit-bridge-addin 0.5.0 or later.

Claude Desktop — claude_desktop_config.json:

{
  "mcpServers": {
    "revit-bridge": {
      "command": "uvx",
      "args": ["revit-bridge"]
    }
  }
}

Claude Code - the plugin (skill + MCP server + confirmation hook, recommended):

/plugin marketplace add revitbridge/revit-bridge
/plugin install revit-bridge@revit-bridge

The plugin's .mcp.json starts the server with uvx; its hooks/hooks.json denies execute_code / run_tool calls that carry no confirmation token (uv run executes plugin/hooks/spec_gate.py, so uv must be on PATH). The skill is also installable on its own with npx skills add revitbridge/revit-bridge.

MCP server only, without the skill and hook:

claude mcp add revit-bridge -- uvx revit-bridge

Any MCP client — run uvx revit-bridge as a stdio server. Pass connection settings through environment variables (see Configure), for example in the env block of the host's server entry.

Your own host — the same flow is a package API: revit_bridge.execution (run_pack, run_code, revalidate) with your own ToolStore, Gate, Ledger and Revit client, plus revit_bridge.host_instructions() for a host whose interface does the confirmation.

From a checkout: uv sync then uv run revit-bridge.

Develop a standalone C# add-in, phase by phase — the skills in plugin/skills/ follow an add-in from the designer's sentence to the release. Each phase skill works on its own; the bridge components (MCP server, revit-bridge-addin, revit-api-docs) only add to a phase, and each phase skill's SKILL.md has a table saying what they add.

Phase

Skill

What it does

Needs a component

Brief

revit-task-brief

Rewrites a one-sentence request ("I pick two crossing pipes and the first one gets jogged over the other") into a testable brief: numbered behaviour, inputs with units and defaults, cancel and failure rules, project facts, deliverables, verification, decisions.

No; with the bridge it reads the project facts itself

Coding

revit-addin-dev

Continues a project or creates a minimal command project for Revit 2024 to 2027, including the 2025.5/2026.5 .NET 10 updates (select the exact installed release, not just its year), and delivers a DLL that runs without the bridge.

No; the bridge adds model context and prototype checks

Bridging

revit-bridge + revit-core

Builds, changes and queries the open model through the server: snapshot, reconcile, confirm, execute, verify.

Yes: the MCP server and the revit-bridge-addin

Test

revit-addin-test

Runs the compiled add-in in a real Revit without disturbing others on the machine, reads journals, finds why Revit hangs, judges a build matrix, compares base and branch.

No; with the revit-bridge-addin calls go through its protocol

Release

revit-addin-release

Multi-year release build, obfuscation, installer, acceptance on a real machine, the review record, logs from a user's machine.

No

Install the skills in another project

The six skills (revit-task-brief, revit-addin-dev, revit-addin-test, revit-addin-release, revit-bridge, revit-core) are self-contained folders: a SKILL.md plus references/, scripts/ and assets/. Any agent that reads skill folders can use them, with or without the MCP server. The four add-in phase skills need no bridge connection at all (testing and acceptance need a real Revit, not the server); revit-bridge and revit-core describe the bridge tools and are most useful with the server configured; in a repository without the server their descriptions only cost context, so install --profile addin there.

Where you work

Install

Claude Code, everything (skills + MCP server + confirmation hook)

/plugin marketplace add revitbridge/revit-bridge then /plugin install revit-bridge@revit-bridge

Claude Code, one project (skills only)

uvx revit-bridge skills install --to .claude/skills in the project

Claude Code, every project of this user (skills only)

uvx revit-bridge skills install --to ~/.claude/skills

Codex, dsh and other agents reading .agents/skills

uvx revit-bridge skills install --to .agents/skills

One skill only

add its name: uvx revit-bridge skills install revit-addin-dev --to .claude/skills

An add-in repository that does not use the bridge

uvx revit-bridge skills install --profile addin --to .claude/skills (revit-task-brief + revit-addin-dev + revit-addin-test + revit-addin-release; --profile bridge is the other pair, revit-bridge + revit-core)

Without uv

pip install revit-bridge then revit-bridge skills install --to <dir>; or copy the folder from plugin/skills/ of a checkout, or npx skills add revitbridge/revit-bridge

From a checkout, without copying

claude --plugin-dir ./plugin

revit-bridge skills list prints the names and descriptions. install copies whole folders, leaves other skills in the directory alone, and refuses to overwrite an existing folder of the same name unless --force is given, so local edits survive an accidental re-install. To upgrade, run it again with --force after uvx has fetched the new release (uvx revit-bridge@latest skills install ...).

The bundled scripts need Python 3.11+ or Windows PowerShell 5.1+: new_addin.py in revit-addin-dev; journal_tail.py, addin_snapshot.py, revit_ps.ps1 and window_list.ps1 in revit-addin-test; collect_logs.ps1 with its collect_logs.bat launcher in revit-addin-release. Nothing else is installed and none of them starts, installs or closes a Revit.

Example request once installed: "Use revit-addin-dev to continue my C# plugin, inspect the selected walls through revit-bridge where needed, and build an independent command." The bundled scripts/new_addin.py --help describes the starter generator; it does not install or launch the add-in.

Related MCP server: Civil3D MCP Server

Use

  1. Start Revit, open a project and make sure the add-in is listening.

  2. Check the connection:

    uvx revit-bridge check

    Prints host, port, whether a token is set, the open document's title (document, or document_error when the add-in answered but could not read it) and "status": "connected", plus capability (supported when the add-in answers get_bridge_capabilities, unsupported for an older add-in, unknown with the reason otherwise) and environment (Revit version and runtime); the exit code is 0 when the add-in answered, 1 otherwise.

  3. In your host, the flow is snapshot → questions → confirmation → execution → validation:

    • get_project_snapshot — what the model contains (units, levels, grids, family types, selection, …); query(kind, args) answers single read-only questions (levels, grids, family_types, elements, selection, view_elements, units, counts). Neither needs confirmation.

    • list_tools — the capability packs (eight built-ins such as create_wall, create_structural_column, query_levels, plus your own); missing_params(tool, known) — the questions still open, with the real options, who can answer each (kind) and the steps it holds up (blocks); get_tool_choices(name) — levels, types or elements for a pack's dynamic parameters.

    • reconcile(spec, snapshot) — a draft TaskSpec against the model: values that do not exist, missing parameters, readings to confirm (units, "on F2"), a stale snapshot.

    • check_code(code, parameters) — compiles C# for execute_code in Revit without running it (no token): diagnostics with lines in your code, hints, and guidance (the lessons for those errors, or pointers once it compiles); checked: false when the add-in cannot (an older add-in).

    • dry_run_code(code, parameters, include) - runs C# in Revit and always rolls it back (no token): what the code returned, what it would have added, modified and deleted (counts by category), and every Revit warning or error; no_dry_run when the add-in has no dry run, and dry_run_not_rolled_back is a defect to report at once. include names local .cs files compiled with the code (at most 20, 400 KB in all), so an add-in's core-logic file is dry-run as it is; it needs an add-in that reports features.dry_run_sources (else no_dry_run_include).

    • test_addin_command(dll, command_class, picks, input, readback_code, zoom_to, timeout_seconds, restore) - runs a built add-in DLL's command in the open model without installing it: picks clicked on elements by id, input from <name>.input.json, then the model is restored (no token). Returns what the command returned, its result file, the changes and every warning the command left to Revit, and the read-back; addin_test_not_restored is a defect to report at once. zoom_view and capture_view move the view and save a picture of it. All three need an add-in that reports features.addin_test (else no_addin_test).

    • get_guidance(stage=...) — lessons for writing Revit code (the snippet contract, units, API pitfalls), chosen by stage, API symbols, OST_* categories, compiler errors and run-time exceptions; read-only, no token.

    • confirm_spec(spec) with the TaskSpec the designer confirmed, then run_tool(name, params, token) with exactly the confirmed values.

    • plan_verification(template, params) / verify_execution(evidence_id, verification_id) — for execute_code: a read-back check (created_ids, count_delta, param_equals) planned before confirming, run after; no token.

    execute_code takes arbitrary C# for tasks no pack covers. The code runs inside Revit with document in scope and a transaction already open; end it with return <object>;. When it throws in Revit, the reply's hint names the get_guidance(stage="fix", exceptions=[...]) call for that exception. solidify_tool saves code that worked as a new pack.

    A pack's validator (created_ids, count_delta or param_equals) asserts the outcome after the run: success is true only when Revit succeeded and the assertion held, and every execution leaves a line in the evidence ledger (evidence, validate(evidence_id)).

Devices and the dialog in Revit. A host that reaches Revit over the network (the web demo) pairs each add-in installation once: DeviceStore.create_pairing() hands out a XXXX-XXXX code that is valid for ten minutes, the add-in redeems it with DeviceStore.redeem(code) and keeps the device token it gets back, and the browser that asked for the pairing keeps a browser key. Only sha256 digests of the code, the token and the key are stored (<data dir>/auth/devices.json); verify_device, verify_browser and revoke are how a host authorises a request afterwards. Each confirmation and each ledger line then carries the scope it belongs to

  • the device_id, or local for the add-in on this machine - and a token confirmed for one device cannot be redeemed on another. Independently of any client setting, execute_code asks the designer once more in Revit: the request carries the confirmed spec card, the add-in shows it with Yes/No and waits up to three minutes, and a No comes back as error: "declined_on_device" (the token is spent and the run is in the ledger). run_tool runs capability packs without that dialog.

Confirmation gate. execute_code and run_tool return confirmation_required without a token. A token comes only from confirm_spec(spec): the TaskSpec lists every parameter with its value, source and evidence; the server validates it and issues a one-time token bound to exactly that tool and those parameters (or that code). Running anything else with it, reusing it, or using it after 10 minutes fails with confirmation_invalid. missing_params and reconcile help build the spec. dry_run_code needs no token: the add-in rolls every dry run back. Hosts that run their own confirmation flow can set REVIT_BRIDGE_ALLOW_UNCONFIRMED=1.

Resources: revit://stats, revit://tools/{name}, revit://evidence/recent, revit://connection-status, revit://guidance/index.

Guidance layers and CLI. get_guidance and check_code read the packaged lessons (framework) and up to three directories laid out the same way: company (REVIT_BRIDGE_GUIDANCE_COMPANY), project (REVIT_BRIDGE_GUIDANCE_PROJECT) and personal (<data dir>/guidance). A higher layer replaces a lesson of the same id, except a company lesson with enforced: true; a layer that fails validation is left out with a layer_invalid warning. uvx revit-bridge guidance check validates them (exit 1 on a problem), guidance index [DIR] [--check] rebuilds the lesson indexes and the revit-core skill export, and guidance explain --stage fix --errors CS1061 --symbols Wall LocationCurve prints what would be recommended, and why. Output of revit-bridge guidance and revit-bridge skills sent to a pipe or a file is UTF-8; in Windows PowerShell 5.1 run [Console]::OutputEncoding = [Text.Encoding]::UTF8 before piping or capturing it, otherwise Chinese text shows as mojibake (revit-bridge check prints ASCII-escaped JSON there and needs nothing).

The plugin ships an eval suite (plugin/evals/, the three baseline tasks and two second-turn cases, with mocks of the MCP server). Run it by hand from plugin/ with claude plugin eval . (on Windows in a UTF-8 console: chcp 65001 first, or the Chinese prompts reach the model garbled); it is not part of CI.

Pair with revit-api-docs

revit-api-docs is an optional second server: search_revit_api looks API names up in the Revit 2026 API reference, and check_code hints point at it. Its data set covers Revit 2026 only, whichever Revit year the add-in runs in; for another year, treat members that changed between releases as unconfirmed. The plugin does not start it: add it with claude mcp add revit-api-docs -- uvx revit-api-docs, or in one config:

{"mcpServers": {"revit-bridge": {"command": "uvx", "args": ["revit-bridge"]},
                "revit-api-docs": {"command": "uvx", "args": ["revit-api-docs"]}}}

Its first run downloads the data set v1.1-data (267 MB; uvx revit-api-docs download fetches it ahead of time): the Revit 2026 API reference, including constructors such as new XYZ(x, y, z) and interface members. From revit-api-docs 0.3.0 on, TYPESAFE_API_KEY alone turns on Jev reranking; Cohere is optional. For multi-step task requests (several steps in one sentence) also set an embedding key, REVIT_API_DOCS_EMBEDDING_API_KEY (OpenRouter, model openai/text-embedding-3-large), to fuse vector search with keyword search. On 223 English test queries the fused nDCG@5 was 0.647 against 0.557 for keyword search alone, both without reranking, and 0.842 with Jev. Each query makes one more embedding call (about 0.9 s, negligible cost); every setting is in its README.

Configure

Variable

Default

Meaning

REVIT_BRIDGE_HOST

127.0.0.1

Host where the add-in listens

REVIT_BRIDGE_PORT

18080

TCP port of the add-in

REVIT_BRIDGE_TOKEN

(unset)

Pre-shared token, sent with every request when the add-in has one configured

REVIT_BRIDGE_TIMEOUT

60

Seconds to wait for a command to finish

REVIT_BRIDGE_ALLOW_UNCONFIRMED

(unset)

1 lifts the confirmation-token gate (host-internal flows only)

REVIT_BRIDGE_CONFIRM_TTL

600

Seconds a confirmation token stays valid

REVIT_BRIDGE_DATA_DIR

%LOCALAPPDATA%\revit-bridge (Windows), ~/.local/share/revit-bridge (else)

Per-user data: solidified packs, usage.json, the evidence ledger, auth/devices.json, verifications/ (read-back plans)

REVIT_BRIDGE_CAPABILITIES_DIR

<data dir>/capabilities

User pack directory; the packs shipped in the wheel stay visible, a user pack of the same name replaces one

REVIT_BRIDGE_EVIDENCE_DIR

<data dir>/evidence

Evidence ledger (<YYYY-MM>.jsonl) and pending confirmations

REVIT_BRIDGE_GUIDANCE_COMPANY

(unset)

Company guidance layer: a directory laid out like plugin/guidance; its lessons replace packaged ones of the same id

REVIT_BRIDGE_GUIDANCE_PROJECT

(unset)

Project guidance layer, above the company one; the personal layer is <data dir>/guidance when it exists

Development:

uv sync
uv run pytest
uv build
uvx --from . revit-bridge check
uv run revit-bridge guidance check plugin/guidance
uv run revit-bridge guidance index plugin/guidance --check

License: MIT. Issues and discussion: https://github.com/revitbridge/revit-bridge/issues.

Use from dsh (DeepSeek Harness)

dsh runs an agent that can talk to revit-bridge and revit-api-docs like any other MCP client, and it iterates on its own: writes, compiles, reads the model, fixes, until the task is done. The flow for a feature developed against the live Revit:

  1. Install the add-in in Revit (Releases of revit-bridge-addin), open the project you want to work on and click Add-Ins > Revit MCP Switch. uvx revit-bridge check must print "status": "connected" with that document's title.

  2. Register both servers in the dsh profile you use (~/.dsh/profiles/<profile>/cordis.patch.yml, a top-level list):

    - insert:
        - id: mcp-revit-bridge
          name: '@deepseek-ai/dsh-mcp-client'
          config: { serverName: revit-bridge, transport: stdio, command: uvx, args: [revit-bridge] }
        - id: mcp-revit-api-docs
          name: '@deepseek-ai/dsh-mcp-client'
          config: { serverName: revit-api-docs, transport: stdio, command: uvx, args: [revit-api-docs] }

    Keys (TYPESAFE_API_KEY, REVIT_API_DOCS_EMBEDDING_API_KEY) and a proxy go into each server's env; dsh strips KEY/TOKEN variables from its own environment, so set them there, not globally.

  3. Put the skills where dsh finds them: copy plugin/skills/revit-task-brief, revit-addin-dev, revit-addin-test, revit-addin-release, revit-core and revit-bridge into <project>/.agents/skills/.

  4. Start dsh in the project directory and give it the task in one or two designer sentences, plus the facts it cannot discover: "Revit 2026 with the test model is open on this machine", whether anyone will answer questions, and what the report must contain. With --profile headless --json it runs unattended and streams events; interactive mode lets you answer the bridge's confirmation requests, which is what lets the agent prototype in the open model (check_code, confirm_spec, execute_code) before it ports the logic into the add-in.

  5. Read the agent's report against the brief (what was built, what it verified in Revit, what it could not), then install the add-in and test the picks, dialogs and cancel paths yourself.

An unattended run cannot confirm execute_code; the agent then verifies by compile checks, model reads and dry_run_code (the code runs in the open model and is rolled back; it needs an add-in with the dry run). Keep the project open on a copy of the model: a prototype that hangs inside Revit blocks the bridge until the request ends.

Available Tools

5 tools
execute_codeA
Destructive

Send C# code to Revit for execution over the local TCP socket. Refused unless spec_confirmed=true (the designer confirmed the task spec). Returns execution result or error message.

Inputs: code (required), parameters, spec_confirmed. Returns: result

get_tool_choicesA
Read-only

Query Revit for dynamic parameter choices of a solidified tool. Call this BEFORE run_tool to discover available levels, family types, etc. Returns {param_name: [{label, value}, ...]} for parameters that need selection.

Inputs: name (required). Returns: result

list_toolsA
Read-only

List all solidified tools available for execution.

Inputs: no named parameters. Returns: result

run_toolA
Destructive

Execute a solidified tool by name with given parameters. IMPORTANT: Call get_tool_choices first for parameters with choices_from / source: query:*. Refused unless spec_confirmed=true (the designer confirmed the task spec). params: JSON object of parameter values, e.g. {"level_name": "L1", "height": 3000}

Inputs: name (required), params, spec_confirmed. Returns: result

solidify_toolB

Save a successful code execution as a reusable named tool. parameters: JSON array of {name, type, description, source?, default?, choices_from?} tags: comma-separated tags

Inputs: code (required), name (required), tags, parameters, +2 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 5 tools

    Disambiguation4/5

    Most tools have clearly distinct roles: execute_code runs raw C#, run_tool runs saved tools, solidify_tool creates them, and list_tools/get_tool_choices support discovery. However, execute_code and run_tool both perform execution, which could cause an agent to misselect when only one is appropriate.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun snake_case pattern: execute_code, solidify_tool, list_tools, get_tool_choices, run_tool. The naming is predictable and makes the surface easy to navigate.

    Tool Count5/5

    Five tools is well-scoped for a Revit bridge: execute raw code, solidify it, list solidified tools, query parameter choices, and run a solidified tool. Each tool earns its place with no unnecessary redundancy.

    Completeness3/5

    The set covers creating, listing, querying, and running solidified tools, but lacks update and delete operations for those tools. There is also no way to view a single tool's details, leaving the lifecycle partially incomplete.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers