max-mcp
Integrates with a running Autodesk 3ds Max session, letting an AI assistant read the current selection, query objects and layers, hide/show layers, capture viewport screenshots, and execute MAXScript or Python (pymxs) in the live scene, with every scene change recorded as a named undo step that can be audited and reverted from 3ds Max's history.
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., "@max-mcp capture the active viewport and list every object on the Walls layer"
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.
max-mcp
Let an AI assistant work inside your running Autodesk 3ds Max session, and keep the user in control of what it changed.
max-mcp is an MCP server for 3ds Max. Any MCP client (Claude Code, Claude Desktop, Cursor, Gemini CLI, ChatGPT developer mode, custom agents over HTTP) can read the selection, query objects and layers, grab the viewport, and run MAXScript or Python (pymxs) in the live scene. Every request is logged, every scene change is a named undo record, and the AI can only undo its own steps.
Why this project - archviz work in 3ds Max is full of repetitive scene surgery (renaming, layer sorting, batch property edits, checks) that an assistant can do well, but only if it sees the open scene and the user can audit and reverse what it did. Headless batch scripts can't see the open scene; most bridges give the AI a raw "run script" tool and nothing else. max-mcp is the small, model-agnostic layer in between. It is also a portfolio piece.
The max-mcp window inside 3ds Max: History tab with per-request undo state, scene diff and the code that ran.
How it works
Piece | Runs in | Depends on |
| 3ds Max (its own Python 3.11) |
|
| your Python 3.10+ | official |
The listener accepts newline-delimited JSON on 127.0.0.1:30025; the MCP server
(stdio or streamable HTTP) forwards tool calls to it. Commands run on Max's main
thread (see below). The bridge never saves your scene and has no save tool.
Tested with 3ds Max 2025 (Python 3.11.8, PySide6 6.5.3). Other versions that
ship pymxs + PySide6 should work but are untested.
Related MCP server: MaxForge MCP
Install
git clone <repo-url> max-mcp
cd max-mcp
pip install . # or pip install -e . (editable)
# without installing: uvx --from . max-mcpNo installer: the listener only needs its folder on sys.path, which the
start script does by itself (it also drops the two action icons into Max's
usericons folder, see below).
1. Load it inside 3ds Max
Scripting > Run Script... and pick max_side/max_mcp_start.ms. The
MAXScript Listener prints [MaxMcp] dinleniyor 127.0.0.1:30025 and the window
is available as macroScript MaxMcp Settings (category max-mcp, add it to
any menu/toolbar/quad via Customize > Customize User Interface), or with
python.Execute "import max_mcp_ui; max_mcp_ui.show()".
Both actions, MaxMcp Settings and MaxMcp Start/Stop (a check button that
stays highlighted while the listener runs), come with SVG icons, so they can go
on the ribbon too: right-click the ribbon > Customize Ribbon, pick category
max-mcp in the action list and drag them onto a panel. The icons live in
max_side/icons/MaxMcp/; the macro file copies them to Max's per-user
usericons\MaxMcp folder when they are missing or changed. That folder is the
only thing written outside the repo besides the optional startup loader.
To load it automatically at startup, press Install loader in the window
(writes a one-line max_mcp_loader.ms into Max's per-user startup folder;
Remove loader deletes it) or use the CLI:
python -m max_mcp.paths # shows detected paths and the loader text, writes nothing
python -m max_mcp.paths --write # writes the loaderWhether the listener actually starts at startup is the autostart setting.
2. Register the MCP server in your client
The window's Client configuration box generates these for your current
port/key (press Copy). Defaults shown; replace python with the interpreter
that has mcp installed.
Claude Code
claude mcp add -s user max -- python -m max_mcp.server
# HTTP transport:
claude mcp add -s user --transport http max http://127.0.0.1:30026/mcpClaude Desktop (claude_desktop_config.json), Cursor (.cursor/mcp.json
or global MCP settings), Gemini CLI (~/.gemini/settings.json) - all use
the same mcpServers shape:
{ "mcpServers": { "max": { "command": "python", "args": ["-m", "max_mcp.server"] } } }Gemini CLI's HTTP form uses "httpUrl": "http://127.0.0.1:30026/mcp"; Cursor's
uses "url". These shapes follow each vendor's public docs at the time of
writing but were not verified by running those clients here; only Claude
Code and the official mcp Python client were tested.
HTTP / remote clients (ChatGPT developer mode, OpenAI/xAI remote MCP tools, custom agents) - run the HTTP transport and point the client at the URL:
python -m max_mcp.server --transport http # http://127.0.0.1:30026/mcp
python -m max_mcp.server --transport http --http-host 0.0.0.0 --key <secret> # LAN; key mandatoryWith a key, clients must send Authorization: Bearer <secret>. Hosted services
need the URL to be reachable from the internet (a tunnel such as ngrok or
cloudflared, over HTTPS) - not verified here, and exposing Max's script
execution to the internet is your risk to take.
Configuration
Settings live in %LOCALAPPDATA%\max-mcp\config.json (override the path with
MAX_MCP_CONFIG) and are edited in the window. Precedence, highest first:
environment variable > command-line argument > config file > default.
Key | Env | Default | Meaning |
|
| 30025 | listener TCP port |
|
| 127.0.0.1 | listener bind address |
|
| "" / false | shared key (env var implies enabled) |
|
| true | start listener with Max (needs loader) |
|
| 50 | main-thread pump interval |
|
| 60 | seconds a call may wait for Max |
|
| 127.0.0.1 / 30026 | streamable-HTTP bind |
|
| off |
|
|
| 10 / 2048 | checkpoint retention |
|
| 5 | history.jsonl size before rotation |
|
| true | may the |
Server CLI: --transport stdio|http --port --host --key --timeout --http-host --http-port --config.
Tools
Tool | Parameters | What it does | Undoable |
| - | version, scene path, dirty flag, units, counts, renderer, listener status | read-only |
|
| selected objects | read-only |
|
| find objects; | read-only |
| - | layers with hidden/frozen/current flags and object counts | read-only |
|
| hide/show a layer | yes - |
|
| active viewport to PNG, returns the path | read-only (writes the PNG) |
|
| run MAXScript; returns the last value ( | yes when |
|
| run Python in Max; | yes when |
|
| the command history (see below) | read-only |
|
| undo the bridge's own records only | it is the undo |
Object records contain name, class, layer, pos, hidden; with detail=true
also superclass, bbox_min/max, rotation, scale, parent, children, frozen, selected, wirecolor, material {name, class}, user_props, faces.
History, undo and checkpoints
Every request is appended to <config dir>/history.jsonl (rotated at
history_max_mb, two older files kept) with time, MCP client name
(clientInfo), tool, argument summary, full args, duration, ok/error, output,
objects added/removed, selection before/after and a "scene changed" flag from
Max's undo put counter. The History tab of the window shows the rows; a row
reveals the full code and output, Copy code and Re-run act on it.
Undo records. Scene-changing tools are accepted as one undo record each,
labelled MCP: <tool> #<id>, so Ctrl+Z in Max undoes exactly one request. An
error inside the record cancels it (partial changes are rolled back) and the
error is returned.
max_undo (the AI). Undoes the last steps records or everything down to
to_history_id - but only if every level on the way is a bridge record. The
bridge reads the real stack (theHold.getUndoNames()), identifies its own
levels by label and depth, and verifies after each max undo. If a user's
manual step sits in between the call is refused and names the step; if the
target has left the undo stack it fails. (When the pump runs inside a
python.Execute call - the dotNet-timer fallback - Max names every level
"MAXScript"; the depth bookkeeping still works, but once the stack is full
and Max starts dropping old levels those records are reported as gone rather
than guessed.) Undone entries are marked
undone in the history; the undo call is itself a history row. The
"AI may undo its own steps" switch in the window turns the tool off
(it then returns "disabled"). There is no max_redo: Max clears the redo
stack on the next change, and the next AI request is a change, so a redo tool
would almost never have anything to redo; Ctrl+Y in Max covers the rare case.
Revert to here (the user). The History tab can undo back to any record still on the stack, including past the user's own steps - after a confirmation that lists them. Rows whose record is gone are grey ("gone" / "undone").
Checkpoints (optional, default off). With checkpoint_mode = changing
(or all) the bridge copies the scene before each request with
saveMaxFile <copy> useNewFile:false quiet:true, which keeps the scene's
own file name and path and never touches your file; the "modified" flag is
restored afterwards. Default off because a full scene write before every
command is slow on large scenes and the undo records already cover normal use;
turn it on for risky sessions. Copies live in <config dir>/checkpoints,
limited by count and total size, oldest deleted first.
Restoring a checkpoint is deliberately NOT an MCP tool. It replaces the
whole scene and discards everything done since, including the user's manual
work, so it only exists as Restore checkpoint in the History tab, behind a
confirmation. The restore goes through Max's Hold/Fetch mechanism (the copy is
placed as maxhold.mx and fetched), so the scene keeps its file name and path
and nothing is written to your file until you save.
The window also shows and sets Max's undo levels (theHold.setMaxUndoLevels).
How the main-thread problem is solved
pymxs must only be used from Max's main (UI) thread. The listener never
touches Max from its socket threads: every request is queued, and a PySide6
QTimer on the main thread drains the queue, runs the handler and hands the
result back through a threading.Event. Max's own Qt event loop fires the
timer. max_mcp_start.ms falls back to a System.Windows.Forms.Timer calling
max_mcp_listener.pump() if the QTimer cannot be created.
Consequences:
A call waits at most
timeoutseconds for the main thread. If Max is busy (rendering, a long script, a modal dialog blocking the event loop) the call returns a timeout error; a job that had not started is dropped, one already running keeps running and its result is discarded.A long command blocks the Max UI for its duration and cannot be interrupted from outside. Keep
max_run_*snippets short or raisetimeoutdeliberately.When Max closes, the socket closes; the MCP server reports "cannot reach the 3ds Max listener" until Max (with the listener) is back. A fresh connection is opened per call, so nothing needs a restart on the MCP side.
Security
The listener binds to
127.0.0.1by default; the HTTP transport too. Binding HTTP to any other address requires a key (the server refuses to start otherwise); clients sendAuthorization: Bearer <key>.max_run_maxscript/max_run_pythonexecute arbitrary code inside Max with your user rights. On a single-user machine any local process already has that power, so the key is off by default; enable it (Generate + "require shared key") on shared machines or whenever HTTP leaves localhost.The bridge never saves the scene. It writes: the history file, optional checkpoint copies, viewport PNGs where you ask for them, and (only through the window's Install/Remove buttons) the startup loader.
Tests
pip install -e .[dev]
pytest # unit tests, no 3ds Max required (fake pymxs, fake undo stack)
python tests/e2e_batch.py # optional: headless 3dsmaxbatch round trip, needs Max installedUnit tests cover the protocol/queue/timeout machinery, every handler against a
fake pymxs, config precedence, the UI-free settings model, history rotation,
undo bookkeeping (own steps only, refusal on user steps, target gone, switch
off), checkpoint naming/pruning, and the streamable-HTTP transport with the
official MCP client (key required / 401 / public bind refused).
The headless test runs the listener with serve_blocking() on Max's main
thread because 3dsmaxbatch has no Qt event loop while a script runs, so the
QTimer pump and the window are only exercised in an interactive Max:
Open 3ds Max, run
max_side/max_mcp_start.ms.In a terminal:
python -c "from max_mcp import client; print(client.call('info'))"-pump_modeshould readqt.From your MCP client:
max_selection, thenmax_run_pythoncreating a box, thenmax_undo- the box disappears; press Ctrl+Z / look at the History tab.
Troubleshooting
"cannot reach the 3ds Max listener" - Max not running, listener not started, or different ports on the two sides. Check the MAXScript Listener for
[MaxMcp] dinleniyor ...;python -m max_mcp.pathsconfirms paths.Every call times out - the pump is not running (modal dialog, timer never created). Close the dialog; Restart in the window.
max_infoshowspump_modeandpump_on_main_thread.max_undorefused - a manual step is on top of the AI's; use the window's Revert (it asks) or Ctrl+Z yourself.Port in use - change it in the window (Save + Restart) and re-copy the client config.
Viewport capture in batch mode - works, but shows the default headless viewport; meaningful only in interactive Max.
Known limitations (found in live testing)
Modal dialogs block the bridge. If a command makes 3ds Max show a modal message box, Max's main thread waits until someone clicks OK. Example: ProBoolean showing "Invalid Boolean". While it waits, every request times out. Prefer operations that do not raise UI, such as building the mesh yourself instead of using a boolean.
Operations that commit their own undo records (ProBoolean, for example) are now merged into the single
MCP: <tool> #idlevel bytheHold.SuperBegin/SuperAccept. Objects created after such an operation in the same command can still end up outside the undo record. Keep these operations in a separate command, or avoid them.Multi-statement MAXScript runs line by line. Statements before a compile error in a later line have already executed.
What makes it different
Several 3ds Max MCP servers already exist, and some are much larger than this one (150–380 tools). This project makes different trade-offs:
The user can see every AI action and roll it back. Each request is listed in a History panel inside Max with its client, code, result and changed objects. The user can return to any listed step with one click. The AI can undo only its own steps (
max_undo): it refuses if a manual user step sits in between. Restoring a scene checkpoint is never exposed as a tool. In the projects we looked at, undo was exposed as a tool the AI calls, and we did not find a user-facing history panel with rollback. This was not an exhaustive survey.Settings live inside Max. Port, bind address, shared key, autostart, AI-undo switch, checkpoints and ready-to-copy client configs are all in one dialog. Other projects use config files, environment variables or an installer.
The tool set is small on purpose (~10 tools, plus MAXScript and Python for everything else). This means less context for the model and a smaller attack surface.
There is no save tool. The bridge never writes over the user's scene file. Checkpoints are copies in a temp folder, and the scene's path and name stay the same.
No dependencies on the Max side. It uses only pymxs, the standard library and Max's bundled PySide6. All work runs on Max's main thread. The project is MIT licensed.
Undo has limits, as it does in every DCC. Effects outside the scene are not reverted by undo: files written, renders started, assets exported. The "Undoable" column in the tool table marks these cases.
Türkçe kısa not
Max'te max_side/max_mcp_start.ms çalıştır (pencereden "Install loader" ile
startup'a yükleyici konur), sonra istemcine python -m max_mcp.server kaydet
(pencerenin "Client configuration" kutusu metni üretir). Köprü sahneyi asla
kaydetmez; her değişiklik MCP: <araç> #<id> adlı bir undo kaydı. max_undo
yalnız yapay zekânın kendi adımlarını geri alır, araya senin adımın girdiyse
reddeder; senin adımlarını da geçen geri dönüş ve kontrol noktası yükleme yalnız
penceredeki onaylı düğmelerle yapılır.
License
MIT - see LICENSE.
Available Tools
10 toolsmax_historyA
Read the bridge's command history (time, client, tool, summary, duration, ok/error, objects added/removed, selection, undo_state). undo_state is 'on_stack' (max_undo can target it), 'undone' or 'gone'. full=True includes complete args and output.
Inputs: full, tool, limit. Returns: result
max_infoA
Check the connection and return Max version, open scene path, dirty flag, units, object/selection counts, renderer and listener status.
Inputs: no named parameters. Returns: result
max_layersA
List all layers with hidden/frozen/current flags and object counts.
Inputs: no named parameters. Returns: result
max_query_objectsB
Find scene objects. name_pattern is a MAXScript wildcard ('Wall_*', 'door', case-insensitive); class_name matches classOf (e.g. 'Editable_Poly', 'Box'); layer matches the layer name. detail=True adds bbox, transform, material, user properties.
Inputs: layer, limit, detail, class_name, +2 more. Returns: result
max_run_maxscriptA
Execute MAXScript inside Max and return the value of the last expression. (format/print output goes to Max's Listener window; return values instead.) undo=True wraps the code in an undo record.
Inputs: code (required), undo, timeout. Returns: result
max_run_pythonB
Execute Python (Max's own 3.11 with pymxs) inside Max. rt (pymxs.runtime)
and pymxs are predefined. A single expression returns its value; for
multi-line code assign to result. print() output is returned too.
Inputs: code (required), undo, timeout. Returns: result
max_selectionB
List the currently selected objects (name, class, layer, position; with detail=True also bbox, transform, parent, material, user properties).
Inputs: limit, detail. Returns: result
max_undoA
Undo the bridge's OWN scene changes: either the last steps undo records
or everything down to and including history entry to_history_id. Only
records labelled 'MCP: #' are undone; if a user's manual step
sits in between the call is refused and names it (the user can revert past
it from the settings window). Fails when the target has left the undo
stack or when AI undo is disabled in the settings window.
Inputs: steps, to_history_id. Returns: result
max_viewport_captureA
Grab the active viewport to a PNG file and return its path and size. path defaults to %TEMP%/max-mcp/capture_.png. max_size limits the longer edge (0 = keep the viewport resolution).
Inputs: path, max_size. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool targets a distinct resource or action: scene info, layers, selection, object querying, layer visibility, viewport capture, MAXScript execution, Python execution, history, and undo. The two execution tools are clearly separated by language, and query vs. selection tools are distinguished by scene-wide filtering vs. current selection. No pair appears to do the same thing.
All names share the max_ prefix and use snake_case, which makes the set predictable. However, some tools are noun-based (max_layers, max_info, max_selection, max_history) while others are verb-based (max_query_objects, max_set_layer_hidden, max_run_maxscript), so the pattern is not fully uniform.
Ten tools is a well-scoped set for a 3ds Max bridge: it covers introspection, selection/query, layer visibility, viewport capture, scripting escape hatches, history, and undo. Each tool has a clear role, and the count avoids both thinness and bloat.
The surface covers core bridge operations well, including scene introspection, object discovery, viewport capture, arbitrary MAXScript/Python execution, command history, and undo. Dedicated tools for common lifecycle actions such as scene save/open, render/export, or direct object creation/transformation are absent, though the scripting tools provide workarounds.
Related MCP Connectors
Control Unreal Engine to browse assets, import content, and manage levels and sequences. Automate…
Build editable 3D scenes, direct characters and cameras, and export AI video references with MCP.
Build and run AI workflows, agents, data tables and 1000+ API integrations from any MCP client.
Read and edit the Revit 2024–2027 model on your PC. Needs the free Revit MCP add-in.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables 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.2418MIT
- FlicenseBqualityCmaintenanceEnables AI agents to control a live 3ds Max session directly, including creating and editing objects, materials, animation, and scene inspection, with undo support.17-
- AlicenseNot gradedqualityBmaintenanceEnables 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
- AlicenseBqualityBmaintenanceEnables AI agents to directly control Autodesk 3ds Max for modeling, shading, rigging, animation, rendering, baking, and engine export through MCP.3753MIT