vred-mcp

A local MCP server that lets MCP-compatible AI clients (Claude Code, OpenAI Codex) inspect and control the currently open scene in a running Autodesk VRED Professional 2027 instance, through a small authenticated bridge that runs inside VRED itself.

Status: Phase 1, 2, and 3 complete, live-verified against a running VRED 2027 instance. 22 tools exist: 13 read-only (connectivity, scene/camera/material/variant inspection, node lookup, bounded scene tree) and 9 mutations (select/clear selection, show/hide, move/rotate/scale, switch camera, capture screenshot), all gated behind VRED_ALLOW_MUTATIONS with a dry_run option that works even when disabled. Every mutation was applied for real against a live scene and confirmed restored to its original values afterward - see IMPLEMENTATION_PLAN.md sections 10-11 for what live verification caught along the way (several doc-reading mistakes, one real networking bug, and one bad assumption about how to reload code changes). Save and basic scene-lifecycle tools are now implemented. The server is now registered with both Claude Code (✔ Connected via claude mcp list) and Codex - Codex was verified with two real non-interactive agent runs that actually called vred_ping and get_scene_summary through MCP and got back correct live VRED data (see IMPLEMENTATION_PLAN.md section 12).

1. Purpose

Give an AI coding/automation agent a safe, auditable way to ask "what's in the currently open VRED scene" and (in later phases) make small, explicit, reversible changes to it - without ever giving the agent the ability to run arbitrary code inside VRED.

Related MCP server: blender-ai-mcp

2. Supported VRED version

Autodesk VRED Professional 2027 (internal version 19.0), confirmed against the actual local installation at C:\Program Files\Autodesk\VREDPro-19.0 (autodesk_VRED_2027.swidtag). Not tested against any other VRED version or edition (VREDDesign, VREDPresenter).

3. Architecture

Claude Code / OpenAI Codex   (MCP client, stdio transport)
        |
vred-mcp server               external Python process (this repo's venv)
        | HTTP over 127.0.0.1 only, Bearer token auth, JSON-only envelope
VRED bridge                   runs INSIDE VRED's embedded Python 3.11,
        |                     loaded via VRED's Script Editor
        | vrTimer-marshaled calls, VRED main/render thread only
Autodesk VRED Professional 2027

Why it's shaped this way (full reasoning in IMPLEMENTATION_PLAN.md):

• VRED's own built-in web interface (http://localhost:8888/pythoneval?...) evaluates arbitrary Python passed in the URL. It is real and documented, but using it directly would make this server a disguised execute_python tool, which the project's own security requirements forbid. So a separate, purpose-built bridge was written instead, with a fixed operation whitelist.

• VRED's embedded Python interpreter (3.11) is a different process/runtime than whatever runs this MCP server - they must talk over a local transport regardless. HTTP over loopback was chosen since it needs nothing beyond the Python standard library on the VRED side.

• VRED's vrTimer fires synchronously with VRED's render loop (documented behavior). The bridge's HTTP handling happens on a background thread; actual VRED API calls are marshaled onto the main thread through a vrTimer callback, so nothing calls VRED's scene API off-thread and nothing blocks VRED's UI.

4. Security model

• The bridge binds only to 127.0.0.1. It refuses to start on any other host, and refuses to start if its auth token is still the placeholder value.

• Every bridge request needs Authorization: Bearer <token>, checked with a constant-time comparison (hmac.compare_digest).

• The bridge accepts only {"op": "<name>", "args": {...}}. <name> must be a key in vred_bridge/command_registry.COMMAND_REGISTRY - a fixed Python dict of handler functions. There is no code path anywhere in this project that takes a string of Python (or a VRED method name) from the network and executes/calls it.

• Request bodies over VRED_MAX_REQUEST_BYTES are rejected without being read into memory.

• Mutation and save operations (Phase 3/4, not yet implemented) are gated behind VRED_ALLOW_MUTATIONS / VRED_ALLOW_SAVE, both false by default.

• The MCP server never logs the auth token (only its length) and never logs full scene dumps or binary image data.

• execute_python, execute_shell, run_command, delete_node, and similar tools are intentionally absent and are not planned - see the main task spec this project was built from.

5. Prerequisites

• Windows, with Autodesk VRED Professional 2027 installed and able to run.

• Python 3.10+ available on PATH (this project was built and tested against the system's Python 3.14.3; 3.11/3.12 also present on this machine work too - uv/pipx are not installed here, so setup below uses a plain venv + pip).

• Claude Code and/or OpenAI Codex CLI installed (claude --version, codex --version).

6. Supported Python version

>=3.10 for the MCP server (see pyproject.toml). The VRED bridge runs under whatever Python VRED 2027 embeds (3.11) and only uses the standard library - it is not installed via pip and has no version constraint of its own beyond "whatever VRED 2027 ships."

7. Installation

cd C:\Users\<you>\autodesk-vred-mcp
.\scripts\install.ps1

This creates .venv, installs the project in editable mode with dev dependencies, and copies .env.example to .env if .env doesn't exist yet. If your PowerShell execution policy blocks running local scripts, either run powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1, or set an execution policy scoped to your user (Set-ExecutionPolicy -Scope CurrentUser RemoteSigned) - the project does not require or configure this itself.

8. Dependency management

Plain pip + venv (uv and pipx were checked and are not installed on this machine, so the scripts don't depend on either). Runtime dependencies: mcp>=1.27.0 (official Python MCP SDK, includes FastMCP), pydantic, pydantic-settings, httpx. Dev-only: pytest, pytest-asyncio, ruff. The VRED-side bridge has zero dependencies beyond VRED's own embedded Python standard library.

9. Token generation

.\scripts\generate_token.ps1

Prints a 64-character hex token. Put the same value in two places:

• .env -> VRED_BRIDGE_TOKEN=<token>

• vred_bridge\bridge_config.py -> TOKEN = "<token>" (or set the VRED_BRIDGE_TOKEN environment variable before launching VRED, which bridge_config.py reads first).

10. .env configuration

Copy .env.example to .env (done automatically by install.ps1) and fill in VRED_BRIDGE_TOKEN. All settings are validated eagerly at server startup (src/vred_mcp/config.py) - a missing/placeholder token, a non-localhost VRED_HOST, an out-of-range port, or an invalid LOG_LEVEL all produce a clear error message on stderr instead of a confusing failure later. See .env.example for the full list of variables and their defaults.

11. How to load the bridge in VRED Professional 2027

Confirmed live against a real running VRED 2027 instance - not just doc text. Full detail (including VRED's sandbox behavior) in vred_bridge/README.md.

1. Recommended: launch VRED with its Python sandbox disabled, so the next steps don't hit a wall of "Allow for this project" popups (VRED 2027 intercepts stdlib networking calls the bridge needs, one function at a time, and clicking through them all is impractical):

   $env:VRED_INSECURE_PYTHON = "1"
   & "C:\Program Files\Autodesk\VREDPro-19.0\bin\WIN64\VREDPro.exe"

   This only affects the one launched process - it does not change any persistent setting. If you'd rather keep the sandbox on, you can click "Allow for this project" through each popup instead; expect several, since different socket operations trigger separate prompts.

2. In VRED, open View > Terminal - this is VRED's Python console (a persistent REPL, prompt root:). This is what the docs call the "Script Editor"; there is no separately-named panel.

3. Type these two lines and press Enter after each:

   __file__ = "C:/Users/<you>/autodesk-vred-mcp/vred_bridge/vred_mcp_bridge.py"
   exec(open(__file__).read())

   (Use forward slashes or escaped backslashes - Python string, not a raw Windows path.)

4. Watch for a line starting with [vred-mcp-bridge]. listening on http://127.0.0.1:8765/rpc ... means it's up; REFUSING TO START: ... explains what's misconfigured (usually the token).

If you close the Terminal panel, its Python session resets - __file__ and stop_bridge() become undefined again next time you open it. This does not stop an already-running bridge (it keeps running as long as VRED does); it only means step 3 needs to be re-run to load a new bridge after a restart.

To reload a running bridge after editing bridge_config.py or command_registry.py (without closing the panel), stop_bridge() + step 3 alone is not enough - confirmed live: Python's module cache means the code changes silently don't take effect and new operations keep returning UNSUPPORTED_OPERATION. Use this instead:

stop_bridge()
import sys
for mod_name in ("bridge_config", "command_registry"):
    sys.modules.pop(mod_name, None)
exec(open(__file__).read())

See vred_bridge/README.md for the full explanation.

A documented fallback that doesn't use the console at all (relaunches VRED with the bridge script base64-encoded on the command line via -postpython) is in vred_bridge/README.md.

12. How to start the MCP server

You normally won't do this by hand - Claude Code/Codex launch it for you (see sections 14/15). To run it manually (e.g. to watch its log output):

.\scripts\start_mcp.ps1

This runs python -m vred_mcp with stdio transport. All logging goes to stderr (and optionally logs/vred_mcp.log) - stdout is reserved for MCP protocol frames.

13. How to test connectivity

Two independent checks, so you can tell a bridge problem from an MCP-client problem:

# 1. Bridge only, bypasses MCP entirely:
.\scripts\test_connection.ps1

# 2. Full path, via the MCP tool itself, once connected to a client:
#    ask Claude Code / Codex to call the `vred_ping` tool.

test_connection.ps1 POSTs an authenticated ping op directly to http://127.0.0.1:8765/rpc and prints the structured JSON response (or a clear error if VRED/the bridge isn't reachable).

14. How to connect Claude Code

Verified against Claude Code 2.1.179 (claude mcp --help).

claude mcp add vred-mcp -s user -- "C:\Users\<you>\autodesk-vred-mcp\.venv\Scripts\python.exe" -m vred_mcp

• -s user registers it for your user account (available in every project). Use -s project instead to write a .mcp.json in the current project directory, or -s local (the default) for this project only, stored outside version control.

• There is no --cwd flag - config.py resolves .env relative to the project's own install location, not the launch directory, so this works regardless of scope.

• See client-configs/claude-code.example.json for the equivalent raw .mcp.json shape if you want to hand-edit instead.

Verify it's connected:

claude mcp list
claude mcp get vred-mcp

Inside a Claude Code session, ask it to list available tools, or just ask it to call vred_ping.

Remove/disable:

claude mcp remove vred-mcp

15. How to connect OpenAI Codex

Verified against codex-cli 0.144.5 (codex mcp --help, and empirically by adding/inspecting/removing a throwaway entry - see IMPLEMENTATION_PLAN.md section 8).

codex mcp add vred-mcp -- "C:\Users\<you>\autodesk-vred-mcp\.venv\Scripts\python.exe" -m vred_mcp

This writes a [mcp_servers.vred-mcp] table into %USERPROFILE%\.codex\config.toml (Codex MCP servers are global, not project-scoped). See client-configs/codex.example.toml for exactly what that block looks like.

Verify it's recognized:

codex mcp list
codex mcp get vred-mcp

Remove/disable:

codex mcp remove vred-mcp

16. How to use read-only mode

The default. VRED_ALLOW_MUTATIONS=false in .env (the default) blocks all 9 Phase 3 mutation tools before any network call is made - they return a structured MUTATIONS_DISABLED error. dry_run=true still works on any of them even in this mode (it validates/resolves everything and reports what would happen, without calling it) - useful for letting an AI agent preview a change before you decide to enable mutations.

17. How to enable mutations

Set VRED_ALLOW_MUTATIONS=true in .env, and make sure the bridge running inside VRED agrees - either launch VRED with the VRED_ALLOW_MUTATIONS environment variable set beforehand, or set it live in VRED's Terminal console for the current session:

bridge_config.ALLOW_MUTATIONS = True

Both sides enforce this independently (defense in depth) - if either says disabled, the call is blocked. The 9 mutation tools: select_nodes, clear_selection, show_nodes, hide_nodes, set_node_translation, set_node_rotation, set_node_scale, activate_camera, capture_screenshot. All were live-tested against a real scene with real before/after values and confirmed fully restored afterward - see IMPLEMENTATION_PLAN.md section 11.

18. How to enable save operations

Set VRED_ALLOW_SAVE=true in .env to enable save and basic scene-lifecycle tools. These operations are restricted to VRED_ALLOWED_SAVE_DIR on both sides.

19. Tool list (current)

All 22 tools below have been exercised through the real MCP server code path against a live running VRED 2027 instance (see IMPLEMENTATION_PLAN.md sections 10-11) - not just unit-tested with mocks. Mutation tools were applied for real and confirmed restored to original values afterward.

Read-only:

Mutations (blocked unless VRED_ALLOW_MUTATIONS=true on both sides - section 17; dry_run=true always works):

Planned tools and their VRED API verification status: VRED_API_COMPATIBILITY.md.

20. Example AI prompts

• "Ping the VRED bridge and tell me if it's connected."

• "What version of VRED is running, and what scene file is open?"

• "Run the VRED diagnostic and tell me whether the bridge, version, and scene summary all look healthy."

• "Save the current scene."

• "Save this scene to a new file inside the approved save directory."

• "Create a new empty scene."

• "Give me a summary of the current scene."

• "Show the scene tree, two levels deep."

• "Find every node whose name contains wheel."

• "What's currently selected?"

• "Show info for the node with unique_path 2:Front."

• "List the cameras in the scene, and tell me which one is active."

• "What variant sets does this scene have?"

• "List the materials in the scene."

• "Select the node with unique_path 2:Front."

• "Hide the node with unique_path 3:Wheel_FL." (needs mutations enabled)

• "Do a dry run of hiding 3:Wheel_FL and show me what would change."

• "Activate the Front camera."

• "Move the node at 3:Wheel_FL to [100, 0, 0]."

• "Take a screenshot and save it to C:\VRED_MCP_OUTPUT\shot.png."

(Prompts involving variant activation still depend on tools that aren't implemented yet - variant sets can be listed but not switched. Save and scene-lifecycle tools are now available, but only inside the approved save directory and behind VRED_ALLOW_SAVE.)

21. Known limitations

• No activate_variant tool - variant sets can be listed (get_variant_sets) but not switched, and listing options within a set isn't implemented either. Confirmed live that createVariantSet takes only a name (no way to test the selection functions against real captured-state data without deeper scene setup) - see VRED_API_COMPATIBILITY.md.

• Save and scene-lifecycle tools are implemented (save_scene, save_scene_as, new_scene), gated by VRED_ALLOW_SAVE and restricted to VRED_ALLOWED_SAVE_DIR.

• get_vred_version's version fields come from static install metadata, not a live VRED API call - see VRED_API_COMPATIBILITY.md for why.

• capture_screenshot's allowed-extension whitelist (.png/.jpg/.jpeg/.bmp) is a reasonable assumption, not confirmed against VRED's actual writer support; it also doesn't call updateRender() first, so it captures whatever's currently rendered, not necessarily a fresh frame.

• Translation/rotation/scale units: VRED's UI was observed set to millimeters, but whether the Python API's raw values always match that display unit wasn't independently confirmed.

• The bridge's Python console session (VRED's Terminal panel) resets its globals whenever that panel is closed and reopened - see section 11 for what that does and doesn't affect, and for the separate gotcha about reloading code changes without closing the panel. (No known limitations remain around client integration - both Claude Code and Codex were verified end to end with real tool calls, not just connection checks. See IMPLEMENTATION_PLAN.md section 12.)

22. Security limitations

• The bridge has no rate limiting beyond the request-body size cap - a local process that has your token can call it as fast as it wants. This is considered acceptable for a single-user localhost tool but is not a DoS-hardened service.

• VRED_MAX_JOBS_PER_TICK (hardcoded to 50 in vred_mcp_bridge.py) bounds per-tick work but a sustained flood of requests could still keep VRED's main thread busier than normal.

• The token lives in plaintext in .env and in bridge_config.py. Treat both like any other local secret (they're gitignored; don't commit them).

• VRED_INSECURE_PYTHON=1 (section 11) disables VRED's own Python sandbox for the whole launched VRED process, not just this bridge script. It's scoped to that one process (not persisted), but be aware it also removes sandbox protection from anything else you run in that VRED session's console while it's active.

23. Troubleshooting

24. How to stop the bridge

From VRED's Terminal console: stop_bridge(). Or just close VRED - the bridge is inside VRED's process, so nothing is left running afterward.

25. How to uninstall / remove the MCP configuration

claude mcp remove vred-mcp     # if added to Claude Code
codex mcp remove vred-mcp      # if added to Codex

Then delete the project directory and (if you set one) any persistent VRED_BRIDGE_TOKEN environment variable you configured outside .env.