vw-bridge
Provides tools for querying and modifying Vectorworks Spotlight fixture data, including fixture counts, layer/channel summaries, equipment lists, plot QC audits, and write-back of fixture patch changes through the Lightwright Data Exchange XML.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@vw-bridge How many VL3600 IPs are on Truss 1?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
vw-bridge
MCP server that exposes Vectorworks Spotlight fixture data to Claude Code (or any MCP client). Watches the Lightwright Data Exchange XML file that Vectorworks writes alongside .vwx files, parses it, and serves queries (counts per layer, channels, weights, plot QC).
No manual export step — VW writes the XML automatically whenever focus switches away from VW.
One-time Vectorworks setup
Open any plot in Vectorworks
File ▸ Document Settings ▸ Spotlight Preferences ▸ Lightwright tab
Tick "Use automatic Lightwright Data Exchange"
Save the XML file in the same folder as the
.vwxMove all desired fields (Inst Type, Channel, Universe, Position, Purpose, Color, Weight, Wattage, Unit Number) from "Available Fields" to "Export Fields"
Click Save as default so all future files use this configuration
You don't need to own Lightwright — this is a built-in VW feature that just writes XML.
Related MCP server: fcp-mcp-server
Install
make install # installs into ~/.config/vw-bridge/venvRegister with Claude Code
From the directory you cloned this repo into:
claude mcp add vw-bridge -- uv run --directory "$(pwd)" python -m vw_bridge.serverOr with an explicit path:
claude mcp add vw-bridge -- uv run --directory /path/to/vectorworks-bridge python -m vw_bridge.serverTools
Tool | What it does |
| Point the watcher at a specific |
| Switch by show name (fuzzy match against folder names) |
| List Lightwright XML files under the shows root, newest first |
| Show watched file + last update timestamp |
| Counts per fixture type, optional layer filter |
| Grand totals: count, weight, wattage |
| Per-layer rollup |
| Channel/universe list, filterable |
| Rental-ready rollup |
| Audit: duplicate channels, missing addresses, unpatched fixtures — see lighting-plot-qc for the full review methodology built on it |
| Full parsed data for one fixture by UID — use before planning a write |
| Find a sibling fixture of a given Inst_Type — source Symbol_Name + Wattage for type swaps |
| Write changes back to VW — emits an LW-style patch the file watcher picks up |
Usage in a Claude Code session
You: How many VL3600 IPs do I have on Truss 1?
Claude: [calls get_fixture_counts(layer="Truss 1")] You have 12 VL3600 IPs on Truss 1.When you make changes in VW and switch focus to Claude Code, the data refreshes automatically.
Development
make dev # installs dev deps into .venv
make test # runs pytest
make lint # runs ruffWrite-back (added 2026-05-19)
The MCP now writes patches directly to the Lightwright Data Exchange XML — Vectorworks' file watcher picks them up and applies the changes. No Lightwright application, no Python-in-VW script required.
Recipe for a fixture type swap:
# 1. Find an existing fixture of the target type (gives you Symbol_Name + Wattage)
target = find_fixture_of_type("Robe iForte LTX")
# {"found": True, "count": 4, "symbol_name": "Robe iForte LTX",
# "wattage": "1250 W", "sample_uid": "1244.1.1.0.0"}
# 2. Confirm the source fixture
src = get_fixture_details("1246.1.1.0.0")
# {"found": True, "fixture": {"inst_type": "Ayrton EagleStrike", ...}}
# 3. Write the patch
write_fixture_patch([
{
"uid": "1246.1.1.0.0",
"fields": {
"Inst_Type": target["inst_type"],
"Symbol_Name": target["symbol_name"],
"Wattage": target["wattage"],
},
}
])VW will apply the change when it next gains focus: the on-canvas symbol swaps, the data fields update, the watcher refreshes the cache.
Safety: the writer refuses Delete operations, unknown field names, and UIDs not in the current snapshot. It warns (does not refuse) when Inst_Type changes without Wattage — the "frankenfixture" risk where the symbol swaps but the wattage stays stale.
Protocol spec: see PROTOCOL.md for the full reverse-engineered protocol and WRITE_GUIDE.md for the practical write playbook, the LW-vs-VW writer asymmetry, and known constraints (native FS path required for FSEvents, symbol must exist in resource library, etc.).
Available Tools
13 toolsfind_fixture_of_typeB
Find an existing fixture of a given Inst_Type, for borrowing Symbol_Name and Wattage.
Returns the first match plus a count of all fixtures of that type. The Symbol_Name and Wattage of the returned fixture are the canonical strings to use when patching another fixture to this type via write_fixture_patch.
Pattern: 'I want UID 1246 to become a Robe iForte LTX. Find me an existing LTX so I can copy its Symbol_Name and Wattage into the patch.'
Inputs: inst_type (required). Returns: object
get_active_fileA
Show which XML file is being watched and when it was last parsed.
Inputs: no named parameters. Returns: object
get_channelsA
Channel + DMX address listing, filterable by layer and/or fixture type.
Includes only patched fixtures. Each entry has channel, dimmer, absolute address, universe, layer, position, inst_type.
Inputs: layer, inst_type, include_old. Returns: object
get_equipment_listB
Rental-style rollup: fixture type, quantity, total wattage.
Sorted by quantity descending. Includes accessories (clamps, gel frames) aggregated separately.
Inputs: include_old. Returns: object
get_fixture_countsA
Counts of each fixture type, optionally scoped to one layer.
By default the "OLD" parking layer is excluded. Pass include_old=True to include it.
Inputs: layer, include_old. Returns: object
get_fixture_detailsA
Return the full parsed data for one fixture by UID (dotted form).
Use before planning a write — the caller usually needs the fixture's current Lightwright_ID (preserved into the patch), current Inst_Type / Symbol_Name / Wattage, and layer / position to confirm it's targeting the right fixture.
Inputs: uid (required). Returns: object
get_fixture_summaryC
Grand totals: fixture count, total wattage, layer count, device-type breakdown.
Inputs: include_old. Returns: object
get_layersC
Per-layer rollup: fixture count, wattage, and unique fixture types.
Inputs: include_old. Returns: object
list_plotsA
List Lightwright XML files under the shows root, newest first.
Each entry has show_folder, xml_path, vwx_path, modified_at. Useful for picking which plot to watch when you have multiple shows open or when set_active_plot returns ambiguous matches.
Inputs: limit. Returns: object
plot_qcC
Audit the plot for common QC issues.
Reports:
duplicate channels (same channel value across multiple fixtures)
duplicate DMX addresses (same absolute_address across multiple fixtures)
unpatched fixtures (no channel and no DMX address)
missing positions
missing purposes
Inputs: include_old. Returns: object
set_active_fileC
Point the watcher at a Lightwright Data Exchange XML file.
The file is the .xml that Vectorworks writes alongside your .vwx (in the same folder) when "Use automatic Lightwright Data Exchange" is enabled in Spotlight Preferences. It updates whenever you switch focus away from Vectorworks.
Inputs: path (required). Returns: object
set_active_plotA
Switch the active plot by show name (fuzzy-matched against folder names).
Examples: 'Aurora Nova', 'Eternal Sunshine'. Picks the most recently-modified XML in the matching show's folder.
Inputs: show_name (required). Returns: object
write_fixture_patchA
Apply field changes to fixtures via the Lightwright Data Exchange XML.
The MCP writes a Lightwright-style patch directly to the active XML. Vectorworks' file watcher picks it up on focus-in and applies the changes to the drawing — no Lightwright the application required in the loop.
Args: changes: list of dicts, each with: - "uid": dotted UID, e.g. "1246.1.1.0.0" - "fields": dict of XML field name → string value, e.g. {"Inst_Type": "Robe iForte LTX", "Symbol_Name": "Robe iForte LTX", "Wattage": "1250 W"}
Returns dict with: written_to, uids_changed, patch_size_bytes, warnings.
Safety: - Refuses Delete operations (the writer is patch-only; Delete is a separate operation we intentionally don't support). - Refuses unknown field names (catches typos before VW sees them). - Refuses UIDs not in the current snapshot. - Warns (does not refuse) if Inst_Type changes without Wattage — this is the 'frankenfixture' risk: new symbol but stale wattage.
To plan a type swap safely: 1. Call get_fixture_details(uid) to confirm target UID. 2. Call find_fixture_of_type(new_type) to get the correct Symbol_Name and Wattage strings. If count is 0, pre-place a fixture in VW first. 3. Call write_fixture_patch with Inst_Type + Symbol_Name + Wattage in the same change.
Inputs: changes (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Most tools target clearly distinct resources and actions: file selection, plot selection, fixture lookups, aggregations, QC, and patching. The main ambiguity is between set_active_file and set_active_plot, and several get_fixture_* rollups overlap in concept but differ in output shape.
The naming pattern is largely consistent verb_noun snake_case: set_active_file, get_layers, write_fixture_patch, etc. The outlier is plot_qc, which is noun-abbreviation rather than verb-first, and find_fixture_of_type is slightly more verbose than the others.
Thirteen tools is well within the well-scoped range and each tool covers a distinct workflow need: plot selection, multiple read aggregations, fixture detail lookup, QC, and patching. No tool feels redundant or padding the surface.
The tool set covers the core workflow of selecting a plot, inspecting it at multiple granularities, running QC, and applying field patches. The main intentional gap is no delete or new-fixture creation, but the descriptions provide clear workarounds by pre-placing fixtures in Vectorworks.
Maintenance
Related MCP Connectors
Read and edit the Revit 2024–2027 model on your PC. Needs the free Revit MCP add-in.
Read and write Mission Control state via MCP — projects, tasks, subtasks, templates, status updates.
Read and write shared BitsWeave context, projects, tasks, and work sessions through MCP.
Run your SupportWire support inbox from any MCP client: conversations, replies, customers, team.
Related MCP Servers
- FlicenseNot gradedqualityAmaintenanceEnables Claude and other MCP clients to read, edit, and generate Final Cut Pro XML timelines, including cut detection, marker and role assignment, transcript-based editing, and pushing cuts into a running Final Cut Pro.-
- FlicenseNot gradedqualityAmaintenanceEnables Claude and MCP clients to read, edit, and generate Final Cut Pro XML timelines, including cut detection, markers, roles, transcript-based editing, rough cuts, and live pushes into Final Cut Pro.-
- AlicenseAqualityBmaintenanceLets Claude work inside an open Vectorworks drawing on macOS, reading and bulk-editing Spotlight lighting devices, checking positions, and exporting channel hookup paperwork. It can also run arbitrary Vectorworks Python, with validated all-or-nothing edits and a tool that undoes exactly the last change.14531MIT
- FlicenseNot gradedqualityAmaintenanceEnables users to let an MCP client read, edit, and generate real Final Cut Pro timelines from exported XML or live projects, covering cut detection, markers, roles, transcript-based edits, keyframes, speed ramps, rough cuts, and cross-NLE export.-