Skip to main content
Glama
README.md
# 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](https://docs.astral.sh/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.

## Install

```bash
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:

```bash
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.

```bash
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:

```python
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

```bash
# 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
```