Skip to main content
Glama

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 是同一套能力在命令行上的入口。

工具

作用

max_status

连接、版本、单位、场景概况。每次会话先调它

max_scene_summary

对象统计、图层、缺贴图

max_query_objects

按名称/类型/图层查节点

max_get_object

单节点详情(变换、修改器、材质、包围盒)

max_set_property

批量改属性

max_create_object

建基础体或导入几何

max_delete_objects

删节点

max_screenshot

抓视口 / 快速渲染,返回图像

max_file_io

导入 / 导出 / 合并

max_eval

执行 MAXScript(万能口)

max_python

在 Max 内跑 Python(逻辑用,场景操作别用)

max_api

查某个类声明了哪些成员及类型

max_api_search

在全量 API 快照里搜类名/属性

max_check

试跑表达式,确认能不能用(自动清理副产物)

max_doc

搜本地 MAXScript 参考

写脚本前先查 API:max_api "Editable_Poly" 看有什么, max_check ["(Box()).wirecolor"] 确认能用。文档和记忆都可能过时,运行中的进程不会。


可靠性设计

修改这一层的代码前,先确认不违反下面这些约束:

约束

内容

错误必须继承 ToolError

MCP SDK 只回传 ToolError 的消息,其他异常一律判为崩溃、只回 Error executing tool <name>。MaxError 因此继承 ToolError,并在末尾附加 [max_error code=... retryable=...]

忙/死判定看任务取走情况

脚本执行期间 Max 的 UI 线程被占,无法轮询,所以轮询间隔不能作为存活依据。任务还在队列里 = Max 没在轮询;任务已被取走 = Max 在跑

结果重投有界

Max 端发件箱上限 16 条,每 tick 补投 1 条,3 次后丢弃;发件箱满时停止取新任务。客户端需等待宽限期才能收到补投结果

max_check 只清理自己创建的对象

通过 #nodeCreated 回调捕获,不扫描全场景。属性赋值、删除、文件写入不会被回滚,删不掉的对象列进 leftover_side_effects

文件操作默认拒绝覆盖

export 需显式 overwrite=True。注意 MAXScript 的 doesFileExist 对目录也返回 true,路径校验必须在 Python 侧用 os.path.isdir

临时文件即用即删

max_python / max_screenshot 用完即删;进程首次调用时按 mtime 清扫历史残留

连不上时的排查顺序:%TEMP%\maxmcp-launcher-<年份>.txt 是否存在 → %TEMP%\maxmcp-boot-<年份>.log 有否 boot finished → 端口是否匹配。

已知限制

限制

说明

POST 没有超时

WebClient 不提供超时设置,maxMcpHttpPost 的 timeout: 参数无效。连接被拒绝是瞬时失败(常见情况),只有「服务端在位但不响应」才会冻结 UI 100 秒。HttpWebRequest 方案不可行:GetResponse() 会抛「请求被取消」

同版本多开

端口按发布年份推导,两个 2016 会争用 47100。可用 MAXMCP_PORT 指定不同端口绕开,Max 端不做自动分配

主线程串行

Max 一次执行一个任务,长脚本冻结 UI 且无法从外部取消,只能在 Max 内按 ESC

max_eval 无限制

可执行任意代码,包括 quitMax()。没有白名单,只能靠 undo 与人工复核

端口规则

port = 47100 + (发布年份 - 2016)

版本

端口

2016

47100

2025

47109

2027

47111

端口只按年份区分,所以同一个版本开两个 Max 会冲突。需要多开时自行指定 MAXMCP_PORT,保证两个实例不同。


连不上时

按层排查:

现象

说明

看哪里

MaxNotConnected

Max 没开,或 bridge 没加载

%TEMP%\maxmcp-launcher-<年份>.txt 存不存在

端口无任何记录

bridge 没在轮询

%TEMP%\maxmcp-boot-<年份>.log 有没有 boot finished

有 LISTENING 无 ESTABLISHED

MCP server 起了但 Max 没连上

端口是否对得上

工具列表里没有 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 tools
max_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_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

    A3.7/5.0

    Scored across 15 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    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
      A
      maintenance
      Connect 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 PyPI
      390
      MIT
    • F
      license
      B
      quality
      C
      maintenance
      Enables AI agents to control a live 3ds Max session directly, including creating and editing objects, materials, animation, and scene inspection, with undo support.
      17
      -
    • 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