max-mcp
You can inspect and control a live 3ds Max session through MCP tools.
Check bridge status, Max build, scene, units, timeline, and renderer.
Execute raw MAXScript or Python inside Max for custom logic and automation.
Reflect/search the running Max API and test whether expressions work.
Search local MAXScript documentation and API references.
Summarize scenes, query objects, and get detailed object data.
Set properties, create primitives/import geometry, and delete nodes.
Capture viewport screenshots or quick renders.
Import, export, or merge FBX/OBJ/MAX files.
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 take a screenshot of my 3ds Max viewport"
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
让 AI 直接操作运行中的 3ds Max 的 MCP 服务器 + CLI。
支持 2016 起的各版本,已在 2016 与 2025 实测通过,两个版本可同时运行、互不干扰。 Max 端是纯 MAXScript,不依赖内置 Python、pymxs 或 PySide6。
安装
1. 装 Python 包(需要 Python 3.10+)
python -m venv .venv
.venv\Scripts\python.exe -m pip install -e .2. 装进 Max
python tools\install.py --list # 看装了哪些版本
python tools\install.py --install # 全部装上它会自动找到安装目录,写两个文件:
<Max>\scripts\maxmcp\max_mcp_bridge.ms ← 真身
<Max>\scripts\startup\start_maxmcp.ms ← 启动桩,只负责加载真身重启 Max 即生效。不需要手动往 startup 里复制任何东西。
3. 配 MCP
在客户端配置里加一条:
"3dsmax2025": {
"command": "<项目路径>\\.venv\\Scripts\\python.exe",
"args": ["-m", "max_mcp.server"],
"env": { "MAXMCP_PORT": "47109" }
}MAXMCP_PORT 对应要连的版本,见下面的端口规则。改完需要刷新客户端并新开会话。
Related MCP server: 3dsmax-mcp
用法
maxctl status # 连接、版本、场景、单位
maxctl doctor # 连不上时先跑这个
maxctl eval "1+1" # 执行 MAXScript
maxctl eval - < script.ms # 从 stdin 读整段脚本
maxctl query --pattern "SM_*" # 列节点
maxctl get Box001 # 单节点详情
maxctl set Box001 --prop wirecolor --value 255,0,0
maxctl create box --name Test --param w=50 --param h=20
maxctl shot --out shot.png # 抓视口,--render 出渲染
maxctl repl # 交互式
maxctl doc "polyop" # 搜本地 MAXScript 参考任何子命令加 --json 出原始 JSON;退出码 0 成功 / 1 工具错误 / 2 用法错误。
工具
MCP 侧暴露 15 个工具,maxctl 是同一套能力在命令行上的入口。
工具 | 作用 |
| 连接、版本、单位、场景概况。每次会话先调它 |
| 对象统计、图层、缺贴图 |
| 按名称/类型/图层查节点 |
| 单节点详情(变换、修改器、材质、包围盒) |
| 批量改属性 |
| 建基础体或导入几何 |
| 删节点 |
| 抓视口 / 快速渲染,返回图像 |
| 导入 / 导出 / 合并 |
| 执行 MAXScript(万能口) |
| 在 Max 内跑 Python(逻辑用,场景操作别用) |
| 查某个类声明了哪些成员及类型 |
| 在全量 API 快照里搜类名/属性 |
| 试跑表达式,确认能不能用(自动清理副产物) |
| 搜本地 MAXScript 参考 |
写脚本前先查 API:max_api "Editable_Poly" 看有什么,
max_check ["(Box()).wirecolor"] 确认能用。文档和记忆都可能过时,运行中的进程不会。
可靠性设计
修改这一层的代码前,先确认不违反下面这些约束:
约束 | 内容 |
错误必须继承 | MCP SDK 只回传 |
忙/死判定看任务取走情况 | 脚本执行期间 Max 的 UI 线程被占,无法轮询,所以轮询间隔不能作为存活依据。任务还在队列里 = Max 没在轮询;任务已被取走 = Max 在跑 |
结果重投有界 | Max 端发件箱上限 16 条,每 tick 补投 1 条,3 次后丢弃;发件箱满时停止取新任务。客户端需等待宽限期才能收到补投结果 |
| 通过 |
文件操作默认拒绝覆盖 |
|
临时文件即用即删 |
|
连不上时的排查顺序:%TEMP%\maxmcp-launcher-<年份>.txt 是否存在 → %TEMP%\maxmcp-boot-<年份>.log 有否 boot finished → 端口是否匹配。
已知限制
限制 | 说明 |
POST 没有超时 |
|
同版本多开 | 端口按发布年份推导,两个 2016 会争用 47100。可用 |
主线程串行 | Max 一次执行一个任务,长脚本冻结 UI 且无法从外部取消,只能在 Max 内按 ESC |
| 可执行任意代码,包括 |
端口规则
port = 47100 + (发布年份 - 2016)版本 | 端口 |
2016 | 47100 |
2025 | 47109 |
2027 | 47111 |
端口只按年份区分,所以同一个版本开两个 Max 会冲突。需要多开时自行指定
MAXMCP_PORT,保证两个实例不同。
连不上时
按层排查:
现象 | 说明 | 看哪里 |
| Max 没开,或 bridge 没加载 |
|
端口无任何记录 | bridge 没在轮询 |
|
有 | MCP server 起了但 Max 没连上 | 端口是否对得上 |
工具列表里没有 | 客户端没启用,或会话没刷新 | 重新启用 + 新开会话 |
Max 里有两个菜单项(Customize > Customize User Interface 搜 max-mcp):
MCP Status — 端口、是否在跑、已服务任务数、最后的错误
MCP Self Test — 验证 JSON 编码器和 timer 状态
设环境变量 MAXMCP_AUTOSTART=0 可让 bridge 只加载不启动,需要时点
MCP Bridge 手动开。
许可
MIT License —— 仓库根目录有独立文件(便于 GitHub 识别授权),下面附一份全文。
Copyright (c) 2026 LxXStudio
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.Available Tools
15 toolsmax_apiA
List the members a class DECLARES. Reflect instead of guessing.
Model memory about MAXScript is unreliable and version-specific -- this session alone produced six wrong assumptions (BooleanClass vs Boolean, formattedPrint format strings, getNodeByName default args, node.layer, byte[].Length, case on strings).
KNOWN BLIND SPOT: this lists only members declared on the class itself.
Node-level universal properties -- name, pos, wirecolor, isHidden,
isFrozen, parent, material -- are NOT in any property list, not even
getPropNames, yet they work. For those, use max_check to test the
expression directly. showClass "*.*" also never lists the abstract node
class, so max_api_search "wirecolor" will not find them either.
Args: class_name: class to inspect, e.g. "Box", "Editable_Poly", "VRayLight". pattern: member name filter, MAXScript wildcard. "*" lists everything, "*segs" narrows to matching members (much shorter output).
Inputs: class_name (required), pattern.
max_api_searchA
Search the ENTIRE API surface of the running Max -- classes and members.
Dumps showClass "*.*" (measured: ~39,700 lines / 1.4 MB on 2016, 3.1 s;
~5.3 s on 2025) to a per-port cache, then greps it. This is the only way to
answer "does this Max have VRayLight?" or "which classes expose wirecolor?"
without guessing from model memory.
Answers, for example: max_api_search "wirecolor" -> every class exposing that property + type max_api_search "VRay" -> which V-Ray classes are actually installed max_api_search "Alembic" -> whether that importer exists here
Args: keyword: case-insensitive substring matched against class and member names. limit: max matches to return. refresh: rebuild the cache even if one exists (after installing plugins).
Inputs: keyword (required), limit, refresh.
max_checkA
Try a list of MAXScript expressions and report which ones actually work.
This is the counterpart to max_api's blind spot. Reflection cannot tell you
whether obj.wirecolor or a plugin property exists, because those are not
in any property list -- but evaluation can. Run them before writing code
that depends on them.
Args: expressions: MAXScript expressions to evaluate in order, e.g. ["(Box()).wirecolor", "(Box()).custom_attr", "units.SystemType"].
Inputs: expressions (required).
max_create_objectA
Create a primitive, or import geometry from disk.
kind: box | sphere | cylinder | plane | teapot | cone | torus | import size keys by kind -- box{w,l,h} sphere{r} cylinder{r,h} plane{w,l} teapot{r} cone{r,h} torus{r,r2}. For kind="import": {"path": "..."}.
Args: kind: primitive type or "import". name: node name (ignored for import). pos: [x,y,z] world position. params: size parameters, see above.
Inputs: kind (required), pos, name, params.
max_delete_objectsB
Delete nodes by name inside one undo block.
Args: names: node names to delete.
Inputs: names (required).
max_docA
Search a local copy of the MAXScript Reference for a term.
Why local: Autodesk retired the 2016 documentation entirely (cloudhelp/2016
returns 404), so max_api-style reflection is the only ground truth for
2016 specifics. The 2025 reference is still published and is the closest
complete prose description of the language; it is crawled into
tools/docs/maxscript-2025 by tools/crawl_maxscript_docs.py.
Use this for "how do I use X" / "what are the arguments of Y". Use
max_api / max_check for "does THIS Max have it" -- prose can be stale
by a release, the running process cannot.
Args: query: term to look for, case-insensitive (e.g. "polyop", "getNodeByName"). limit: max matching pages. snippet_chars: characters of surrounding context per hit.
Inputs: query (required), limit, snippet_chars.
max_evalA
Execute raw MAXScript in the live Max session and return the resulting value.
This is the escape hatch for everything the structured tools do not cover.
The code runs verbatim (no wrapper is added), so write a complete
expression and wrap multi-statement code in ( ... ). The value of the
last expression is serialized back to JSON:
Integer/Float -> number, String -> string, Point3 -> [x,y,z], Array -> array (first 2000 items), node/material/anything else -> its name.
Nothing is auto-saved and no undo block is opened for you. Wrap writes in
undo "label" on ( ... ) when you want them reversible.
Args: code: MAXScript source. Multi-statement code must be wrapped in ( ). timeout_seconds: how long to wait before giving up (Max may still be busy).
Inputs: code (required), timeout_seconds.
max_file_ioC
Import, export, or merge geometry files (FBX / OBJ / MAX).
Args: action: "import" | "export" | "merge". path: absolute file path. selected_only: export only the current selection.
Inputs: path (required), action (required), selected_only.
max_get_objectA
Full detail for one node: transform, modifier stack, material, hierarchy, bbox.
Cheaper and safer than a max_eval for "tell me everything about this object".
Args: name: exact node name, e.g. "Box001".
Inputs: name (required).
max_pythonA
Execute Python inside Max (2.7 + MaxPlus) -- a second engine, chosen explicitly.
WHEN TO USE THIS (measured on real Max 2016, see tests/bench_*):
pure computation, string building, dict/list work: Python is 7-100x faster than MAXScript (100k loop 6 ms vs 55 ms; 5k string concat <1 ms vs 177 ms)
scene access is the opposite: creating 200 boxes MAXScript 30 ms vs MaxPlus ~260 ms; walking 200 nodes MAXScript 1 ms vs ~2 ms. So: never drive the scene from here. Use it for logic, parsing, data shaping, or MaxPlus-only APIs, then hand the result back.
The script runs with result as the value that gets returned:
result = [n.GetName() for n in ...]
Set result on the last line; anything JSON-serializable works.
CAVEATS on Max 2016: Python is 2.7 and the object API is MaxPlus, which Autodesk removed in 2017 (replaced by pymxs). Code written against MaxPlus will not survive a Max upgrade, unlike MAXScript.
Args:
code: Python source. Assign to result for the return value.
timeout_seconds: how long to wait before giving up.
Inputs: code (required), timeout_seconds.
max_query_objectsA
List scene nodes matching a filter. Returns compact rows, not full dumps.
Row fields: name, class, layer, material, verts, faces, pos, hidden, frozen, children.
Scanning stops as soon as limit rows are collected, so truncated: true
means "there are more matches", not an exact total.
Args: name_pattern: MAXScript matchPattern syntax, e.g. "Box*", "SM_*_LOD0", "*". class_name: exact class filter such as "Box", "Editable_Poly", "VRayMesh". Empty = all. layer: exact layer name. Empty = all. limit: max rows to return (1-2000). offset: skip this many matches first, for paging.
Inputs: layer, limit, offset, class_name, +1 more.
max_scene_summaryA
Aggregate the whole scene: class histogram, missing bitmaps, layers.
Use this to orient yourself before writing queries -- it answers "what kind of scene is this, and is anything broken" in one call.
Args: top_n: how many entries to keep in the class histogram.
Inputs: top_n.
max_screenshotA
Capture the active viewport (or a quick render) and return it as an image.
Use this to verify a change actually looks right instead of inferring from coordinates. Rendering is slower (seconds) but respects camera and lights.
Args: render: False = grab the viewport framebuffer (instant); True = render the active view (honours materials and lights). width: render width when render=True. height: render height when render=True.
Inputs: width, height, render.
max_set_propertyA
Set one property on many nodes inside a single undo block.
Examples: prop="wirecolor" value=[255,0,0]; prop="name" value="SM_x"; prop="pos" value=[0,0,100]; prop="visibility" value=False.
Args: names: node names to touch. prop: property name as MAXScript sees it (getProperty/setProperty). value: number, string, bool, or 3-element list for Point3.
Inputs: prop (required), names (required), value (required).
max_statusA
Check the bridge and report 3ds Max build, scene, units, timeline, renderer.
Call this first in a session: it tells you whether Max is reachable, which scene is loaded, and what units the numbers in every other tool mean.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Most tools map to clearly distinct resources/actions (get_object vs query_objects vs scene_summary vs create/delete/set_property), and descriptions explicitly state when to prefer one over another. The overlap is concentrated in the introspection cluster (max_api, max_api_search, max_check, max_doc) and the two execution engines (max_eval vs max_python); the prose disambiguates them, but an agent could still pick the wrong one for 'does this exist' questions.
Every tool uses a uniform max_ prefix with snake_case, which makes the set instantly recognizable. The only deviation is naming style: some tools are verb_noun (query_objects, get_object, set_property, create_object) while others are bare nouns (status, screenshot, file_io, scene_summary, doc), which slightly weakens predictability without being confusing.
Fifteen tools sits at the upper bound of a well-scoped set, and for a full DCC bridge with introspection, scene CRUD, and screenshotting this is defensible. There is mild redundancy: geometry import is exposed both as max_create_object kind="import" and as max_file_io action="import", which is one tool too many for that operation.
Read (query/get/summary), write (create/set_property/delete), file I/O, and visual verification are all covered, plus max_eval/max_python as a genuine escape hatch. Gaps remain for common workflows — no modifier add/remove, no material assignment, no animation/keyframe tools, no scene save/open, and no selection manipulation — but the escape hatches let an agent work around all of these.
Related MCP Connectors
Connect your AI assistant to Blender for 3D modeling, Geometry Nodes, materials, lighting, animation, rendering and export. Inspect real scenes and viewport images, refine the result and restore checkpoints. OAuth connects your chat to Blender Bridge Desktop on an online Windows 10/11 x64 computer running Blender 4.2+. The chat can run on another device. Requires an active Blender Bridge account; 7-day trial available. AI model access is separate.
Control Unreal Engine to browse assets, import content, and manage levels and sequences. Automate…
AI for Revit: 450+ tools, 1 undo step. Windows, Revit 2024–2027 (2021–2023 included). Free account.
Read, query, edit and render DWG drawings with AI. No AutoCAD required.
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
- AlicenseNot gradedqualityAmaintenanceConnect AI agents to Autodesk 3ds Max through the Model Context Protocol, enabling natural language control of scene creation, materials, modifiers, rendering, and plugin workflows.273 PyPI390MIT
- 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