Skip to main content
Glama

max-mcp

Drive an open Autodesk 3ds Max session from an MCP client: run Python in it, read the scene back as structured data, and photograph the viewport so the assistant can look at what it built instead of guessing.

Built for and with Claude Code. The bridge listens on its own port (20228) so it can run next to bridges for other DCC apps.

Requirements: Windows, 3ds Max 2025 or newer (Python 3.11 inside Max), Python 3.10+ and uv for the server.

How it fits together

MCP client  ──stdio──>  max-mcp server        (this project's venv, Python 3.12)
                             │
                             │  TCP 127.0.0.1:20228, length-prefixed JSON
                             ▼
                        max_mcp_bridge        (inside 3ds Max, Python 3.11)
                             │
                             ▼
                          pymxs  ──>  the scene

Two halves, two interpreters. bridge/ is loaded by 3ds Max and may import pymxs; src/ runs in this project's virtualenv and must not. protocol.py is the one file that exists in both, byte-identical, and a test fails if the copies drift.

Each request opens its own short-lived connection, so Max can be closed, reopened or crash without leaving the server holding a dead socket.

The main-thread rule

pymxs is single threaded. Calling rt.something from the socket thread does not raise — it corrupts Max's internal state and crashes it minutes later, somewhere unrelated. Every operation therefore has to run on the thread that owns the scene.

Maya hands you maya.utils.executeInMainThreadWithResult for this. Max has no equivalent, but it is a Qt application, so bridge/max_mcp_bridge/mainthread.py builds one: a QTimer parented to the Max main window ticks every 20 ms on the main thread and drains a queue. The socket thread parks a job there and blocks until the answer comes back, exceptions and all.

If that pump is not running, mainthread.run refuses the work rather than touching pymxs from the wrong thread. That is why start() insists on being called from the main thread — from the Python listener or a startup script.

Max's warm-up window

For roughly the first 20 seconds after launch Max is still loading plug-ins and building its UI. Viewport grabs taken in that window can come back at the wrong shading level or from a view that has not settled. Captures during it carry an explicit warning telling you to re-take the shot rather than quietly handing you a misleading picture.

Related MCP server: max2021-mcp

Install

git clone https://github.com/elturky38/max-mcp
cd max-mcp
uv sync
python install.py

install.py:

  1. writes an Autodesk application package to C:\ProgramData\Autodesk\ApplicationPlugins\MaxMcp\ — a PackageContents.xml and a MAXScript stub in scripts/post-startup/. Max runs .ms at launch, not .py, so the stub's only job is to hand control to bridge/max_mcp_startup.py;

  2. registers the max server in this folder's .mcp.json and, if it exists, the parent folder's .mcp.json — the client reads the config of the directory it was started in;

  3. launches Max's own python.exe to prove it can import the bridge from where the stub points.

To register it by hand in Claude Code instead:

claude mcp add max -- uv run --directory <path to max-mcp> max-mcp

Nothing is copied: the bridge is wired by path, so editing the source here takes effect the next time Max starts.

Why not the per-user startup folder

The obvious place for the stub is %LOCALAPPDATA%\Autodesk\3dsMax\<version>\ENU\scripts\startup\, which is what Max's own Additional Startup Scripts directory points at. Max will not load anything from there: it refuses startup scripts that live under a hidden or system directory, and Windows marks AppData hidden and AppData\Local system. The only trace is a line in Max.log:

INF: Hidden/System startup script: '...\scripts\startup\maxMcpStartup.ms', skip loading...

The same applies to every tool installed there — on this machine Max was silently skipping three of them. The ApplicationPlugins package is loaded through a different code path that does not make the check, needs no admin rights, and is what Autodesk's own plugins use.

Because a startup that fails is otherwise invisible, every stage writes to %LOCALAPPDATA%\Autodesk\3dsMax\max-mcp-startup.log, and the first line is written by the MAXScript stub itself: no log at all means Max never ran the stub, which is a different fault from a bridge that ran and failed. python install.py --check prints the tail of it.

python install.py --check      # report, change nothing
python install.py --uninstall  # remove the stubs and the config entry

To start the bridge in a Max session that is already open, paste this into Scripting > Scripting Listener, Python tab:

import sys; sys.path.append(r"<path to max-mcp>\bridge")
import max_mcp_bridge; max_mcp_bridge.start()

Set MAX_MCP_AUTOSTART=0 to leave the bridge dormant at launch and start it by hand.

Tools

tool

what it is for

max_status

is Max reachable, what is open — call this first when anything fails

max_run

run Python in the live session

max_scene

units, frame range, renderer, counts, selection, hierarchy

max_object

one object in detail: transform, bbox, topology, modifiers, material, keys

max_viewport

a PNG of the viewport

max_undo

take back the last N operations

max_batch

run Python in a fresh headless Max (3dsmaxbatch)

max_batch retries once when Max dies a second or two into its own startup — which it does occasionally, with exit code -1. Nothing of the submitted code has run at that point, so the repeat is free of side effects; a job that fails later, or that reported anything at all, is never repeated.

max_run semantics

The code runs like a REPL cell: if the last line is an expression, its value comes back. rt (pymxs.runtime), its alias mxs, and pymxs are already imported, and names you define persist across calls, so a session can build up helpers instead of resending them.

MAXScript with no pymxs equivalent goes through rt.execute("...").

Return values are coerced into JSON: nodes become {"node": name, "class": ...}, Point3s become [x, y, z], object collections become lists, and anything unrecognised degrades to its repr rather than failing the whole call.

One call, one undo

Every max_run is wrapped in a single undo chunk named by undo_name, via pymxs.undo (falling back to theHold if that is unavailable). The artist sees one meaningful entry in their undo history and max_undo(1) backs the whole thing out.

max_undo also reports whether the object list actually changed, because max undo returns nothing and a no-op undo is otherwise indistinguishable from a successful one.

One trap worth knowing before editing executor.py: pymxs.undo swallows any exception that reaches it. Its context manager catches the exception and drops it if Max's own handler claims it, so code that lets errors propagate out of the undo block turns every failure into a silent success with a null result — the worst possible behaviour for a tool an assistant trusts. The executor therefore catches and records the failure inside the block, and test_in_max.py has a test that fails if that is ever undone.

Viewport capture

max_viewport sets the view, shading mode and grid, forces a redraw, grabs the frame with gw.getViewportDib(), and restores every setting afterwards — including the view transform — because the artist is usually sitting in front of that same window.

The grab arrives at whatever size the viewport happens to be, which is both unpredictable and usually larger than anyone needs, so width and height are treated as a bounding box: the image is only ever shrunk, and keeps its aspect ratio. Both the delivered and the native size come back with it.

Qt does the resampling. MAXScript's own route for this — a bitmaptexture put through renderMap — returns a black image of exactly the right size, which is the kind of failure that passes every test you would think to write. There is a test that samples the pixels.

focus frames a named object or the selection, padded to 75 % so the subject reads as a shape rather than filling the frame edge to edge.

Configuration

variable

effect

MAX_MCP_HOST / MAX_MCP_PORT

where the bridge listens (default 127.0.0.1:20228)

MAX_MCP_TIMEOUT

seconds the server waits for Max (default 120)

MAX_MCP_AUTOSTART=0

do not start the bridge when Max launches

MAX_MCP_BRIDGE_DIR

folder holding max_mcp_bridge, if not bridge/

MAX_MCP_INSTALL_GLOB

where to look for 3ds Max installs

MAX_MCP_MAXBATCH / MAX_MCP_PYTHON

exact paths to 3dsmaxbatch.exe / Max's python.exe

MAX_MCP_PREFS_ROOT

folder holding the per-version preference folders

Tests

# logic that needs no Max: framing, REPL splitting, result coercion
python -m unittest discover -s tests -p "test_pure.py"

# the same suite under the interpreter Max actually ships
"C:\Program Files\Autodesk\3ds Max 2025\Python\python.exe" -m unittest discover -s tests -p "test_pure.py"

# the real bridge against real Max, over a real socket (needs Max open)
uv run python tests/test_in_max.py

# the whole stack over the real MCP protocol, as a client sees it
uv run python tests/test_mcp_server.py

# headless jobs (slow: each case starts a whole Max)
uv run python tests/test_batch.py

test_in_max.py creates and deletes objects under a maxMcpTest_ prefix, so it is safe to run against a scene you care about.

Layout

bridge/                     loaded by 3ds Max; may import pymxs
  max_mcp_startup.py        what the startup stub runs
  max_mcp_bridge/
    __init__.py             start / stop / status
    service.py              socket listener and operation dispatch
    mainthread.py           the Qt-timer hand-off to Max's main thread
    executor.py             REPL semantics, undo chunking, JSON coercion
    scene.py                budgeted scene and object descriptions
    capture.py              viewport grabs
    batch_runner.py         entry point for headless 3dsmaxbatch jobs
    protocol.py             framing  (copy 1 of 2)
src/max_mcp/                this project's venv; must not import pymxs
  server.py                 the MCP tools
  client.py                 one short-lived connection per request
  batch.py                  spawning 3dsmaxbatch
  paths.py                  finding Max, its python, its preferences
  protocol.py               framing  (copy 2 of 2)
install.py                  application package + MCP registration + verification

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to directly control Autodesk 3ds Max through natural language to create models, set materials, adjust lighting, and automate animations. It bridges the Model Context Protocol with 3ds Max via a TCP socket to execute Python and MAXScript commands.
      24
      18
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables execution of Python and MaxScript code inside Autodesk 3ds Max 2021 from Cursor or other MCP clients via HTTP+TCP bridge.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to connect to Autodesk 3ds Max via the Model Context Protocol, allowing natural-language control of scene creation, modeling, materials, viewport capture, and plugin introspection through dedicated MCP tools.
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables AI agents to directly control Autodesk 3ds Max for modeling, shading, rigging, animation, rendering, baking, and engine export through MCP.
      375
      3
      MIT