Vectorworks MCP Codex Plugin

Codex plugin for Vectorworks 2024/2025 on Windows. It packages skills, helper scripts, and an MCP server wrapper for the companion vectorworks-mcp checkout.

Install

/plugin marketplace add BhaveshY/vectorworks-mcp-codex-plugin
/plugin install vectorworks@vectorworks-mcp-codex-plugin

Prerequisites

• Windows with Vectorworks 2024 or 2025.
• PowerShell available on PATH.
• A local checkout of the companion vectorworks-mcp repository unless the plugin is being run from a repo that already contains the connector sources.

Companion repo override

If the companion checkout is not found automatically, set the canonical override before launching Codex:

$env:VW_MCP_REPO = "C:\path\to\vectorworks-mcp"

VECTORWORKS_MCP_REPO remains supported as a backward-compatible alias by the bundled scripts, but new setup should prefer VW_MCP_REPO.

Use

• Open Vectorworks on the same machine as Codex.
• Use the setup, diagnose, ping, and work skills from the plugin root.
• The plugin starts the Python MCP wrapper through plugins/vectorworks/scripts/run-vectorworks-mcp.ps1.

Native bridge status

The repository includes a native Vectorworks SDK bridge scaffold under native_bridge/, but it is not compiled or installed by default. The default bridge remains bridge_kind=python_dialog_agent_session, which keeps CAD API access marshaled through Vectorworks' dialog/event context. Raw socket reachability is not enough to prove CAD API safety.

Why this is not as simple as a Revit-style setup yet

Vectorworks Python scripts run inside the Vectorworks process and CAD API calls must be scheduled on a safe Vectorworks context. A Revit-style connector can usually rely on a mature external-event model; this Vectorworks bridge still needs explicit native SDK build/install steps before it can replace the dialog-agent-session launcher.

Native bridge doctor/smoke examples

Dry-run an explicit native bridge artifact install plan:

powershell -ExecutionPolicy Bypass -File .\scripts\doctor-native-bridge.ps1 -BuiltArtifact C:\path\to\VectorworksMCPBridge.vwlibrary -Install -WhatIf

Install an explicit native bridge artifact after review, then restart Vectorworks:

powershell -ExecutionPolicy Bypass -File .\scripts\doctor-native-bridge.ps1 -BuiltArtifact C:\path\to\VectorworksMCPBridge.vwlibrary -Install
# Restart Vectorworks

Run the native smoke harness after a bridge candidate is listening:

powershell -ExecutionPolicy Bypass -File .\scripts\smoke-native-bridge.ps1 -Phase 1 -PingCount 3 -ReadCount 2
powershell -ExecutionPolicy Bypass -File .\scripts\smoke-native-bridge.ps1 -Phase 0 -Stop -Json

After installing, enable/load the native VectorworksMCPBridge plug-in in Vectorworks, then rerun the doctor. If the scaffold has been copied into a Vectorworks SDK example project, wire-native-bridge-project.ps1 can wire the reviewed bridge sources. The native doctor reports nextCommand, nextCommandReason, and nextCommandSpec plus safety metadata including requiresNetwork, mayInstallSoftware, and rerunDoctorAfter.

Notes

• VW_MCP_HOST, VW_MCP_PORT, and VW_MCP_PREFLIGHT_CACHE_MS can tune the MCP wrapper/listener connection.
• On Linux CI, PowerShell/Vectorworks-specific tests are skipped; Codex plugin manifest validation is platform-independent.