Actions (opt-in)

Read-only by default. Actions are a separate tool set you enable on purpose. Transaction warnings are dismissed and reported in warningsDismissed (omitted when empty); errors that cannot be safely resolved roll back the action.

Action tools have no document or timeout arguments. They use the default timeouts and require exactly one instance returned by the transport. HTTP addresses one endpoint; the file transports discover workstation instances. All IDs are unitless Revit element IDs. Revit 2022–2023 accept IDs up to 2,147,483,647 only; larger IDs fail on those years.

Tool	Arguments	Action and units
revit_select	element_ids	Select IDs; [] clears selection. Return count, the current selection size after the call.
revit_show	element_ids, select=true	Show nonempty IDs; return activeView, viewOpened and count, the current selection size after the call. With select=false, count reports the previous selection.
revit_isolate	element_ids, reset=false	Temporarily isolate IDs; element_ids=[] with reset=true clears hide/isolate.
revit_move	element_ids, dx_mm, dy_mm, dz_mm=0	Move by model-axis offsets in mm.
revit_place_family	family, type_name, x_mm, y_mm, level, rotation_deg=0	Place a loaded family at model XY in mm on a named level; rotate about Z in degrees.
revit_create_wall	start_mm, end_mm, level, wall_type, height_mm=3000	Create a straight wall; endpoints are [x,y] in model mm.
revit_set_parameter	element_id, parameter, value	Set a string value by parameter name; lengths use mm, areas m2, other doubles internal units.
revit_delete	element_ids	Delete nonempty IDs and their dependents.
revit_batch	steps, dry_run=false	Execute 1–50 actions with a single undo entry named revit_batch.

type_name and wall_type are required arguments that accept null.

revit_move, revit_place_family, revit_create_wall, revit_set_parameter and revit_delete accept a final dry_run=false argument. A dry run executes the mutation, reads its prospective result, and rolls back the transaction. A successful dry run includes data.dryRun:true, data.rolledBack:true and the same verification shape as a real write. An action that throws returns an error without a verification block; a missing family also returns closestFamilies on the single-action tool. revit_isolate has no dry_run argument; it uses temporary isolation only. Created IDs in a dry run are provisional and do not identify persisted elements.

Successful real writes return data.dryRun:false and re-read the affected elements after commit. verification.before is captured before the change; verification.after is re-read after commit or before rollback on a dry run. verification.error reports a failed post-commit re-read; the change is committed. Single-action responses include failedStep:null. The verification block contains model facts: bounding boxes for moves, parameter values and ownership for parameter edits, element metadata for creation, and deleted/dependent IDs with a survival check for deletion. Bounding boxes use model XYZ in mm rounded to one decimal; unavailable bounding boxes are omitted. For example, setting Comments on element 123 returns:

{
  "dryRun": false,
  "verification": {
    "before": {"id": 123, "parameter": "Comments", "value": "", "storageType": "String", "owner": "instance"},
    "after": {"id": 123, "parameter": "Comments", "value": "Reviewed", "storageType": "String", "owner": "instance"},
    "changed": [123]
  }
}

revit_batch takes action names and their normal snake_case arguments:

{
  "steps": [
    {"action": "move", "args": {"element_ids": [123], "dx_mm": 100, "dy_mm": 0}},
    {"action": "set_parameter", "args": {"element_id": 123, "parameter": "Comments", "value": "Reviewed"}}
  ],
  "dry_run": false
}

A successful batch assimilates its transactions into one undo entry named revit_batch. The first failed step rolls back the entire batch; every attempted step, including the failing one, carries rolledBack:true. An Assimilate failure is reported on the last step with failedStep pointing at it. All steps are validated before execution; an invalid later step rejects the whole batch without executing anything and without failedStep. Results include zero-based index, command, success and data or error per attempted step, plus undoName, committed and failedStep (null on success). A batch dry run executes every step against preceding steps' changes, then rolls back the group and restores the original selection. A per-step dry_run:true inside a real batch is accepted and previews only that step. Verification describes each step's immediate result; subsequent steps may change those elements again. Batches accept 1–50 steps; select and isolate are allowed, while show, nested batches and unknown argument keys are rejected.

revit_show checks the open UI views before calling ShowElements. If none contains a requested element, it opens a non-template plan for an element's level. Floor plans take priority, followed by names starting with the level name. Without a matching plan it uses the first non-template 3D view. The handler sets UIDocument.ActiveView synchronously inside its ExternalEvent without a transaction; ShowElements needs the view active immediately. RequestViewChange defers the change until control returns to Revit. The response includes activeView and viewOpened, which reports whether the handler opened a previously closed view.

During action execution, the handler attempts to dismiss TaskDialog prompts with OK and then Yes. Messages from successful overrides appear in dialogsSuppressed. The dialog handler is removed in finally, including on errors. For the single-action revit_place_family tool, missing families return up to five similar names with their family categories in closestFamilies; unrelated names are omitted. Inside revit_batch, a missing family surfaces only as steps[].error text; closestFamilies is unavailable. For Family: Type, type_name=null uses the embedded type; a conflicting type_name is rejected. For a family name alone, type_name=null selects the first loaded type.

Both gates must be enabled:

1. Set REVIT_MCP_ALLOW_WRITE=1 in the Python server process environment and restart the server. With any other value or no value, MCP list_tools does not include the action tools.
2. Create %LOCALAPPDATA%\RevitModelMcp\allow-write on the Revit workstation:

New-Item -ItemType Directory -Force "$env:LOCALAPPDATA\RevitModelMcp" | Out-Null
New-Item -ItemType File -Force "$env:LOCALAPPDATA\RevitModelMcp\allow-write" | Out-Null

The add-in checks the gate file for every action, including selection and navigation. Without it, the response contains success:false and error:"actions disabled on the workstation". Removing the file disables actions immediately; restarting Revit is unnecessary. The gate stays in the default local application data directory even if the transport uses REVIT_MCP_CHANNEL_DIR.

Actions address the process ID reported by the transport. Coordinates use model axes and the named level's project elevation. Pass null for type_name to choose the family's first type, or for wall_type to choose the first basic wall type. Family placement uses the level-based, nonstructural overload; hosted, face-based and adaptive families may require another placement API and return an error. The single-action family placement tool returns up to five closest loaded names for an unloaded family. Parameter values use invariant numeric notation; other Double parameters use Revit internal units. Type parameter edits affect all instances of that type and return parameterScope:"type". ElementId and read-only parameters cannot be set.

Responses from the action executor include activeView, including action errors. Transport rejection and target-mismatch responses may omit action metadata. Model changes and temporary isolation use individual transactions named after the tool. revit_batch wraps the per-step transactions in a TransactionGroup named revit_batch and assimilates them into one undo entry. Warnings at commit are dismissed and reported on successful actions. Errors permit one FixElements or SetValue resolution when Revit allows it; unresolved or repeated errors roll back the transaction. Selection and navigation use UI calls without model transactions. The tools do not save the model. After a timeout, inspect the model before retrying an action; the previous call may have executed.