Vectorworks MCP
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| VWMCP_APP | No | The Vectorworks application name for the server to control, e.g. "Vectorworks 2025" when using a different Vectorworks version. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Tools for a live Vectorworks session (Spotlight-focused). This server talks to "Vectorworks 2026" only; every call runs inside that app's open document via the "MCP Run Job" menu command.
Start a session with vw_list_documents (or vw_ping, which lists them too): several documents are often open and the user switches between them. Name the target on every write with document=; the write is refused if another document is active. Test writes belong on a throwaway document.
Vectorworks merges back-to-back MCP edits into one Cmd-Z step, so to undo exactly one tool call use vw_revert_last (works for typed write tools).
Objects are identified by UUID (stable across calls); never cache handles.
Vectorworks embeds Python 3.9: code sent to vw_exec_python must be 3.9- compatible. Use vw_vs_lookup to find vs.* functions and signatures.
Prefer typed tools (lighting devices, records, find) over raw Python.
vw_screenshot shows the document window as an image without touching Vectorworks: use it to check drawn results, or to see a blocking dialog when other tools time out.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| vw_list_libraryA | Browse the Vectorworks libraries: find library files on this Mac by words in their path, or list the symbols inside one file. Read-only, imports nothing. Without |
| vw_import_resourceA | Import one symbol or plug-in style from a library file into the open document. Goes through Vectorworks' own importer, so the resource arrives complete (a truss symbol brings its Braceworks record, a fixture symbol its Lighting Device data). Changes the document's resource list only; nothing is placed in the drawing. Afterwards place it with vw_insert_symbol (plain symbols) or the typed insert tools (truss runs, lighting devices). One revertible step: vw_revert_last removes the imported resource. Returns {name, type_code} with the name as it exists in the document. |
| vw_create_pioA | Place one Vectorworks or Spotlight plug-in object by its internal name and set its parameters. The general-purpose way to create a plug-in object when no typed tool fits; prefer vw_insert_truss_run, vw_insert_lighting_devices, vw_insert_stage_decks and the other insert tools where they exist, since those know the objects' quirks. The object is created and regenerated with the given parameters; nothing else in the document is touched. Unknown parameter names abort the call and nothing is placed. One revertible step. Returns the new object's summary as vw_find_objects lists objects ({uuid, type, name, layer, class, bbox...}) plus class; read the resulting fields with vw_get_record. |
| vw_create_layerA | Create a design layer or a sheet layer in the open document. Adds the layer only; nothing is drawn on it. For a sheet with a viewport and title block use vw_create_sheet instead. The user's active layer stays active unless activate=True. One revertible step: vw_revert_last deletes the layer. Returns {name, kind, active}. |
| vw_create_classA | Create one class in the open document with default attributes. For a whole consistent class set with colours and line weights use vw_apply_class_standard instead. The active class is left unchanged and no object is moved into the new class (pass class_name= to the insert tools, or vw_set_record). One revertible step: vw_revert_last deletes the class. Returns {name}. |
| vw_apply_class_standardA | Give the document a consistent set of Spotlight classes with colours and line weights. Use it once per show file so plots look tidy and layers can be filtered; for a single ad-hoc class use vw_create_class. Missing classes are created and styled; existing ones are left alone unless overwrite=True. No object changes class: afterwards pass class_name= to the insert tools or use vw_set_record. One revertible step (created classes are deleted, restyled ones restored). Returns {standard, created: [...], restyled: [...], unchanged: [...], note?}. |
| vw_create_sheetA | Create a presentation sheet: a sheet layer with one Top/Plan viewport of chosen design layers and an optional title block.
Use it to make a printable plot page; vw_create_layer makes a bare layer
only. The viewport shows |
| vw_delete_objectsA | Permanently delete objects by UUID; the one write that vw_revert_last cannot undo. Only Cmd-Z inside Vectorworks can bring them back, and the deletion also blocks reverting earlier journaled edits, so confirm with the user before calling it. To undo something a tool placed, use vw_revert_last instead of deleting by hand. All-or-nothing: if any UUID is unknown nothing is deleted. Returns {deleted: n}. |
| vw_move_objectsA | Move objects by an offset, keeping their rotation and everything else. All-or-nothing on unknown UUIDs. One revertible step: vw_revert_last moves them back (a plug-in regeneration between move and revert can leave an object off by a fraction of a unit). Returns {moved: n}. |
| vw_set_viewA | Change the drawing view or zoom to fit, typically before vw_screenshot. Changes how the user sees the document, not the document itself, so it is not journaled and vw_revert_last does not undo it. For a view-independent picture use vw_render_layers instead. Returns {view, fit}. |
| vw_insert_truss_runA | Place a straight run of truss pieces end to end, or stack them into a tower, linked into one truss system the way Spotlight's Insert Truss tool does.
Creates |
| vw_insert_truss_pathA | Build a truss shape (L, U, rectangle, any polyline with matching bends) from straights and corners, one chained system.
Each leg takes as many whole straight pieces as fit; a corner piece sits
at every interior point and takes its own length from both legs, so legs
end up shorter than the path by the leftover |
| vw_list_trussA | Inventory of the truss in the document, grouped by truss system in chain order.
Reads only. Each system lists its pieces in order along the chain with
count, total length and weight, symbols, position names, each piece's 3D
centre and the run's plan bounding box (document units, independent of
the current view); |
| vw_insert_hoistsA | Place Spotlight hoists (BrxHoist plug-in objects) at points, one revertible step. Each hoist gets the symbol's capacity, chain weight and length, motor weight, voltage, speed and motor height (from the symbol's HoistObjectData, as the Hoist tool does), its ID, location, function, direction and hook height. Linking to a truss system is left to Vectorworks' own hoist tools. All-or-nothing; vw_revert_last removes every hoist placed. Returns {symbol, count, hoists: [{uuid, id, x, y}], class?}; the derived values (hook height, chain length, weight) exist after the regeneration: read them with vw_list_hoists. |
| vw_list_hoistsA | Inventory of the hoists (BrxHoist objects) in the document for rigging paperwork. Reads only. Sorted by location then ID. Returns {count, total_capacity_kg, hoists: [{uuid, id, symbol, location, function, direction, capacity_kg, hook_height_mm, hook_height (as Vectorworks formats it), weight_with_chain, truss_system_top, truss_system_bottom, notes, class, layer, x, y}]}. |
| vw_insert_lighting_devicesA | Hang a row of lighting fixtures as real Spotlight Lighting Devices with position, unit numbers, channels and purpose set.
Places the symbol |
| vw_insert_stage_decksA | Build a platform from Spotlight Stage Deck objects tiled edge to edge in a grid.
Creates |
| vw_insert_platformA | Build a platform of Stage Decks together with one flight of Stage Steps on a chosen edge, as one revertible step.
The decks are laid out exactly as vw_insert_stage_decks does; the flight
is centred on the |
| vw_insert_bandA | Place a band or crew on stage: people or backline symbols at given points, each with a name label. The symbols must already be in the document (vw_list_symbols); bring them in first with vw_list_library and vw_import_resource. For a single symbol without a label use vw_insert_symbol. All-or-nothing; one revertible step removes symbols and labels together. Returns {members: [{uuid, label_uuid, ...}], class?}. |
| vw_insert_stage_rampA | Place a Spotlight Stage Ramp descending from a stage edge.
Same placement convention as vw_insert_stage_steps: (x, y) is the top
centre on the edge, the ramp runs away from the stage along |
| vw_insert_soft_goodsA | Place a Spotlight Soft Goods run (curtain, truss border or pipe-and-drape) along a path of points.
Creates one Soft Goods object on the open polyline through |
| vw_insert_stage_stepsA | Place a flight of Spotlight Stage Steps descending from a stage edge.
(x, y) is the top centre of the flight on the edge and the flight runs
away from the stage along |
| vw_pingA | Check that Vectorworks answers: one tiny job through the bridge. Read-only. Returns {vectorworks_version, build, document (the active one), bridge_version, documents (all open ones), warning?}. The warning says when the installed bridge is older than this server expects or when this Vectorworks version is untested. Call it once at session start, after vw_list_documents. If it fails or times out, call vw_doctor (which never touches Vectorworks) and vw_screenshot (to see a blocking dialog). |
| vw_doctorA | Check this Vectorworks MCP setup on this Mac without touching Vectorworks. Checks: bridge installed in the right Plug-ins folder and up to date (with its check tables), the 'MCP Run Job' command file present, Claude Desktop / Claude Code configured for this Vectorworks version, Vectorworks running, stale job files, recent log errors. Returns {ok, checks: [{name, ok (true / false / null = could not check here), detail, fix}], next_step, installed?}. Use it first when vw_ping fails; vw_ping is the live test that this one deliberately does not do. Not checked here: whether 'MCP Run Job' is in a menu and the macOS Automation permission. |
| vw_exec_pythonA | Run arbitrary Python inside Vectorworks; the last resort when no typed tool fits. Prefer the typed vw_* tools (they verify and revert precisely); give
Changes the document when the code does. Objects the code creates are revertible with vw_revert_last; changes to objects that existed before (moves, attributes, deletions) are not, and such a call blocks stepping further back. Returns {ok, value, stdout, error, traceback, created, revertable, warning?, lint_warnings?}. |
| vw_lintA | Check Python meant for Vectorworks without running it. Finds syntax errors, vs.* calls with a wrong number of arguments, deprecated calls (these would open the blocking "Script Errors" window) and functions a published safety sweep found to crash or hang Vectorworks or to open a dialog; unknown vs.* names are warnings. Works without Vectorworks running. Argument types and values are not checked here (the bridge checks types when the code runs). vw_exec_python and vw_exec_python run this check themselves, so call it directly only to check a script you do not intend to run yet. Returns {ok, errors, warnings, api}. |
| vw_list_documentsA | List the documents open in Vectorworks, front to back, and which one is active. Read-only; asks macOS from outside Vectorworks (no job, no Accessibility permission). Returns {documents: [names], active, paths: {name: path}} for the paths this server has learned. Every other tool works on the active document, so call this at session start and before writes; switch with vw_switch_document. Fails with "No document is open" when only the start screen shows. |
| vw_switch_documentA | Bring one of the open, saved Vectorworks documents to the front. Changes only which document is active (no drawing change); verified afterwards by reading the front window's name. All other tools act on the active document, so use this before writing when vw_list_documents shows the wrong one in front. Returns {active, switched, documents}. |
| vw_export_geometryA | Read the 2D geometry of one design layer as numbers, in document units. Read-only. Lines and polygons come as points, arcs as centre / radius / angles, texts with origin and string, dimensions with their text; groups are descended, plug-in objects (chain dimensions, doors) are one entry each. Use it to verify what is really in the file, or to compare fill and pen attributes with neighbouring objects before drawing in the same style; vw_render_layers draws the same data as a picture, vw_screenshot shows the real window instead. Returns {document, layer, objects: [{type, class, uuid, points | origin | center, attrs?...}], truncated}, or with out_path {path, count, by_type, by_class, extent}. |
| vw_render_layersA | Draw design layers as a PNG from their real geometry, whatever the Vectorworks window shows. Read-only; one geometry job per layer, no Screen Recording needed. Use it to check drawing work on any layer, visible or hidden; vw_screenshot shows the real window instead (and any blocking dialog), vw_export_geometry returns the same data as numbers. It is a check picture, not a plot: object colours, solid fills and line weights are shown; hatches, dash styles, opacity and curved polyline segments are not, texts are marked with a small cross at their origin, and symbols / plug-in objects are grey boxes. Returns the image. |
| vw_duplicate_layerA | Copy a design layer with all its objects, to try a variant without touching the original. Changes the document: one new layer, one revertible step (vw_revert_last deletes the copy). The copy keeps the scale and is placed right after the source in the layer list; the active layer stays active. Use vw_create_layer for an empty layer. Returns {document, layer, source, objects, source_objects, after_source, scale, visibility, uuid_map when asked for}; objects below source_objects means not every object was copied. |
| vw_set_verticesA | Replace every vertex of one polygon or polyline with a new point list. Changes the document; one revertible step (vw_revert_last restores the previous vertices). Works the same for both object types (the plain vs.SetPolyPt silently does nothing on polylines). Use vw_move_objects to shift a shape unchanged. Returns {points (read back), area_before, area_after, applied, warning?}; applied is false when Vectorworks did not take every point. |
| vw_vs_lookupA | Search the vs.* scripting API of the running Vectorworks by keyword. Read-only (one small job). Use it before writing code for vw_exec_python: it shows the signature the bridge will enforce. Returns [{name, doc (signature and description as Vectorworks ships them), types (the parameter types the bridge checks, "name:TYPE, ..." plus the codes), safety (null, or "crash" / "hang" / "interactive" / "document_level" from the safety sweep: crash and hang are refused, interactive needs allow_dialogs)}]. |
| vw_document_infoA | Describe the active Vectorworks document: name, path, units, active layer and class, counts. Read-only, one small job. Returns {name, path (empty for an unsaved document), units: {display_name, area_name}, active_layer, active_class, layer_count, class_count, selection_count}. Use it to confirm which document a write will land in; vw_list_documents lists all open documents without a job. |
| vw_list_layersA | List every layer of the active document, design and sheet layers alike. Read-only. Returns [{name, kind (design / sheet), visibility (Vectorworks' numeric code), active}] in the document's layer order. Create layers with vw_create_layer, copy one with vw_duplicate_layer. |
| vw_list_classesA | List the class names of the active document, optionally filtered by a substring. Read-only. Returns the names as strings, in Vectorworks' order; class hierarchy shows as "Parent-Child". Create classes with vw_create_class or a whole set with vw_apply_class_standard. |
| vw_get_selectionA | Describe the objects the user has selected on the active layer. Read-only. Returns [{uuid, type, type_code, name, class, layer, bbox, records (attached record names)}]. Use it when the user says "this one"; vw_find_objects searches by criteria instead. UUIDs stay valid across calls. |
| vw_find_objectsA | Find objects in the active document by class, layer, type, plug-in, record or name. Read-only; every given criterion must match (all are exact, not substrings). Returns [{uuid, type, name, class, layer, bbox, records, symbol or plugin name}], the same shape as vw_get_selection. For Lighting Devices with their fields use vw_list_lighting_devices instead. |
| vw_get_recordA | Read every field of one record on one object, or a plug-in object's parameters when no record is named. Read-only. Returns {record (the name resolved, which is also what vw_create_pio needs as the plug-in name), fields: {field name: value as text}}. Write with vw_set_record; for Lighting Devices prefer vw_list_lighting_devices and vw_set_lighting_device_fields, which know Spotlight's rules. |
| vw_set_recordA | Set fields of one record on one object, or a plug-in object's parameters when no record is named. Changes the document; one revertible step (vw_revert_last restores the previous values). Unknown field names are rejected before anything changes. For Lighting Devices use vw_set_lighting_device_fields, which applies Spotlight's address rules and verifies the result. Returns {uuid, record, after: the whole record read back after the change, so values Vectorworks rejected show their actual state}. |
| vw_list_symbolsA | List the symbol definitions already in the active document's resources. Read-only. Returns [{name, folder}]. These are the names vw_insert_symbol and vw_insert_lighting_devices accept; a symbol that is not in the document yet comes in from a library with vw_list_library and vw_import_resource. |
| vw_insert_symbolA | Place one instance of a symbol from the document's resources at a point. Changes the document; one revertible step (vw_revert_last deletes the instance). For lighting fixtures use vw_insert_lighting_devices, which also converts them to Lighting Devices; for truss use vw_insert_truss_run. Returns {uuid, name, layer, class, x, y, z}. |
| vw_revert_lastA | Undo exactly the most recent write this server made in the active document. Changes the document (back to its previous state for that one call). Every typed write tool records what it changed; this restores previous field values, vertices, class attributes, deletes objects, layers and classes that were created, or writes the inverse Lightwright patch. Call it repeatedly to step further back. Not possible: vw_delete_objects, and a vw_exec_python call that created nothing (it only changed existing objects); such an entry blocks stepping further back. Use this instead of Cmd-Z, which merges consecutive scripted edits. Returns {reverted_tool, ...what was restored or deleted, note?}. |
| vw_screenshotA | Capture the Vectorworks document window as an image, without going through Vectorworks. Read-only; no job and no Apple Event (unless mapping is requested), so it works even while a dialog blocks every other tool. Use it to check drawn results or to see what is in front; vw_render_layers draws layers from their geometry instead, independent of the window. Returns the image plus JSON {window (screen geometry), path (saved PNG), in_front (dialogs or open menus that stall jobs), mapping? or mapping_error?, view?}. |
| vw_point_to_worldA | Turn a pixel of the last mapped screenshot into drawing coordinates. Pure arithmetic, no job, read-only. Use it to say where something seen in the picture is, such as the gap a truss should fill, or to check that an object landed where it looks. Needs a prior vw_screenshot(mapping=True). Exact in Top/Plan views only; otherwise the result carries a warning. Returns {x, y, units, warning?}. |
| vw_list_lighting_devicesA | List the Spotlight Lighting Devices in the live drawing, one row per device, sorted by position then unit number. Read-only; one job inside Vectorworks. Each row has |
| vw_set_lighting_device_fieldsA | Change fields of one or more Lighting Devices in the live drawing, verified by reading them back, as one revertible step. Changes the document. This is the default way to edit device data; use
vw_import_hookup for many rows from a spreadsheet export and
vw_lightwright_patch only for Lightwright round trips or when a dialog
blocks the bridge. Every selector and field name is validated first; if any
fails, nothing changes. Universe / DMX Address edits are applied through
UniverseAddress (Spotlight's source of truth), so set that field rather than
Universe or DMX Address alone. Undo exactly this call with vw_revert_last.
Returns one item per device with |
| vw_list_positionsA | List the lighting positions in the live drawing with the devices hung on each, plus the devices that have no position and position names no object carries. Read-only; one job inside Vectorworks. Positions are Light Position Objects, Lighting Pipes, Pipe Ladders, Truss and Hanging Positions, matched to devices by the device's Position field (a text match, so a typo shows up here as a position name without an object). Returns {positions: [{name, type, uuid, devices or count}], without_position: count, names_without_object: [...]}. Use vw_list_truss for truss runs by system and vw_list_lighting_devices for the device rows themselves. |
| vw_lighting_device_reportA | Produce paperwork from the live Lighting Devices, such as a channel hookup or an instrument schedule, as CSV or JSON text and optionally a file. Read-only in Vectorworks; writes only the file you name. Returns the full report text (the same text is written to output_path). For rows to reason about rather than a document to hand over, use vw_list_lighting_devices; to load a hookup back in, vw_import_hookup. |
| vw_mvr_checkA | Check the Lighting Device data for the gaps that make an MVR export incomplete, before the user runs File > Export > Export MVR. Read-only; nothing changes and the export itself is a menu action the user runs (there is no scripting call for it). Errors, which would break or empty the MVR (My Virtual Rig) file: no GDTF fixture type, no fixture mode, missing or duplicate Fixture ID, no DMX patch, overlapping DMX footprints in one universe, footprint past channel 512. Warnings: device without position, position name with no position object, symbol with 2D geometry only (exports as empty geometry), symbol missing from the document. Returns {ok, device_count, summary: {check: count}, issues: [{check, severity: "error" | "warning", message, devices: [{uuid, position, unit, channel}]}], document, next_steps}; a "field_missing" issue lists the fields this document lacks, whose checks were skipped. Fix findings with vw_set_lighting_device_fields (Fixture ID, UniverseAddress, Position, Fixture Mode), the Object Info palette (GDTF fixture) or by importing a hybrid symbol (vw_list_library, vw_import_resource), then check again. |
| vw_import_hookupA | Load a channel hookup or instrument schedule from a spreadsheet export into the Lighting Devices, as a dry run first and then one revertible step. Changes the document only with dry_run=False. Each row is matched to exactly
one device by |
| vw_lightwright_snapshotA | Read the Lighting Devices as Spotlight's Lightwright Data Exchange file last exported them, from the XML beside the saved document. Read-only. The file itself is read without a job (only the document's path
is asked from Vectorworks), so this works even while a dialog blocks the
other tools, but it shows the plot as of the last export, which can be older
than the drawing; vw_list_lighting_devices is the live view. Returns
{available, path, exported (timestamp), fields, count, fixtures: [{uid,
lightwright_id, accessories, ...}]}; {available: False, hint} when the
exchange is off (the hint says how to switch it on); and count 0 with a
|
| vw_lightwright_patchA | Change Lighting Device fields through Spotlight's Lightwright Data Exchange file instead of a job, for Lightwright round trips or when a dialog blocks the bridge. With dry_run=False this changes the document, indirectly: the patch is
written beside the .vwx and Vectorworks applies it 1 to 2 s after it next
gains focus, so the user has to click into Vectorworks; verify afterwards
with vw_list_lighting_devices. Prefer vw_set_lighting_device_fields when the
bridge works. Refuses deletes, fields not in the export, a Symbol_Name no
fixture uses yet (an unknown symbol breaks fixture selection drawing-wide,
irreversibly) and a type change without Wattage. Before writing, the full
export is copied to ~/.vwmcp/lightwright/ ( |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 53 tools
Despite 53 tools, the descriptions sharply separate overlapping operations and explicitly point to alternatives (truss run vs truss path vs create_pio; decks vs platform vs steps; symbol vs lighting device vs band). A few generic-vs-typed creation pairs remain close, but the guidance is strong enough to prevent most misselection.
Names are consistently vw_-prefixed snake_case and mostly follow verb_noun (vw_insert_truss_run, vw_list_lighting_devices, vw_set_record). Minor deviations such as vw_ping, vw_doctor, vw_lint, and vw_screenshot are readable but break the pattern.
The broad Vectorworks/Spotlight domain justifies many operations, and each tool has a purpose, but 53 tools is well above a practical agent-facing ceiling. The volume creates a heavy selection and workflow burden even with good cross-references.
Core create/read/update/undo workflows are covered richly, especially for stage, truss, lighting, layers, classes, and scripting. However, lifecycle gaps remain: no delete/rename for layers or classes, no object rotation/scale/copy, and no document open/save or standard file export tools.