/3dsmax-mcp-dev

name: 3dsmax-mcp
description: Tool choices, workflows, and MAXScript pitfalls for controlling 3ds Max via MCP.

3ds Max MCP — Agent Guide

Tool Profile Routing

• **Full/core:** Operational tools such as `query_scene` and `create_object` are advertised directly; call the matching tool by name.
• **Progressive:** If the advertised surface contains only `list_toolsets`, `describe_toolset`, and `call_tool`, never call an operational name as a top-level MCP tool. Choose the relevant capability with `list_toolsets`, load only that group with `describe_toolset`, then invoke the selected operation through `call_tool(name=..., arguments=...)`.
• Do not describe every toolset up front. Load only the group needed for the current request; if the exact operational tool and arguments are already known, `call_tool` can dispatch it directly.

Principles:

• Match the user's request. Do not run setup, discovery, or scene analysis by habit.
• Do not call `get_bridge_status` or `get_session_context` as a session preamble.
• Prefer a dedicated MCP tool over raw MAXScript when a tool clearly matches the task.
• Do not render unless the user explicitly asks. Viewport capture is fine when visual proof is useful.
• Multiple Max instances: `list_max_instances`, `select_max_instance(pid)`, `get_selected_max_instance`, and `release_max_instance` are available in every profile. The first successful native connection stays bound to that Max. Starting or claiming another Max only changes the default for unbound clients. If the selected Max closes, explicitly select another or release it; clients never silently switch. `MCP_MAX_PID` or `MCP_MAX_PIPE` pins the startup target (`MCP_MAX_PIPE` takes precedence). Release also clears startup pinning.

Tool Choice

Scene reads — use **`query_scene(action=...)`**:

• `overview` | `filter` | `class` | `property` | `selection` | `delta`
• **`get_instances`** / **`get_dependencies`** — instancing and reference graph
• **`resolve_node_refs`** — turn a name, handle, or absolute JSON-Pointer hierarchy path into a canonical handle/name/path identity; multiple selectors are cross-checked
• **`scene_qa(action="scan")`** — deterministic naming, transform, hierarchy/group, and timeline checks only; it never analyzes meshes, UVs, topology, normals, skinning, or visual quality
• **`get_session_context`** — bridge + capabilities + overview + selection (on demand only)

Object/material/plugin inspection:

• `inspect_object`, `inspect_properties`, `get_material_slots`, `get_materials`, `get_material_library`
• `analyze_node_orientation` — pivot, bbox, local axes, world matrix before rig/vehicle/camera transforms
• `introspect_class`, `introspect_instance`, `introspect_osl`, `discover_plugin_classes`, `map_class_relationships` — unfamiliar plugin APIs and exact param names
• Arnold materials such as `ai_standard_surface` may not appear in class discovery; inspect with `inspect_plugin_class` or `introspect_osl`

Lighting:

• `lighting_capabilities` → `create_lights` → `inspect_lights` → `edit_lights`.

Choose a supported renderer route, shape and explicit output unit. A finite bulb is `area/sphere`; an HDRI dome is `environment`. Never infer integer enum meanings.

• Distances accept scene/mm/cm/m/in/ft. Area emitters take a complete size and an

aim point or direction. RGB values are linear in the rendering color space; Kelvin is explicit. EXR/HDR inputs get no extra gamma; preserve the renderer's input primaries conversion and exposure. Existing sky maps can be bound directly.

• For other plugin settings, use `inspect_plugin_class`/`inspect_plugin_instance`

with `schema_version=2`, a query or exact fields. Follow returned map references and pass schema/state tokens to `plugin_patch`. Named enums use `{"enum":"name"}` from the returned choices. Shared or animated resources require deliberate handling.

Mutation:

• Use object, modifier, material, controller, organization, and viewport tools when they match.
• Use `scene_patch` for a preflighted batch of rename, relative transform, visibility/freeze/render flags, or parenting edits that must commit as one native undo step. Pass the mutation-only `expected_scene_seq` from `resolve_node_refs` when stale targeting matters; selection and sub-object selection do not invalidate it.
• Use `scene_qa(action="fix")` only for its explicit deterministic naming fixes; preview with `dry_run=true` when the caller has not already approved the repair.
• Verify after meaningful edits with `query_scene(action=delta)`, re-inspection, or viewport capture.

Debugging:

• `walk_references` — trace dependencies from a live object
• `watch_scene` — track user actions during an interactive session
• `execute_maxscript` — fallback only when no dedicated tool exists
• `execute_python(code)` — embedded Python fallback with `pymxs`; assign a JSON-compatible `result` to return a value alongside stdout/stderr. Requires bridge safe mode off. Calls have fresh variables and one undo step for undoable scene edits; uncaught errors roll those edits back and return a traceback. File I/O and other non-undoable effects persist.

Scene Organization

**Layers** — `manage_layers`:

• Actions: `list`, `create`, `delete`, `set_current`, `set_properties`, `add_objects`, `select_objects`
• Properties: hidden, frozen, renderable, color, boxMode, castShadows, rcvShadows, xRayMtl, backCull, rename, parent

**Groups** — `manage_groups`:

• Actions: `list`, `create`, `ungroup`, `open`, `close`, `attach`, `detach`

**Named Selection Sets** — `manage_selection_sets`:

• Actions: `list`, `create`, `delete`, `select`, `replace`

Tool Reference

Scene reads

`query_scene` `resolve_node_refs` `scene_qa` `get_hierarchy` `get_instances` `get_dependencies`

Atomic scene edits

• `scene_patch` — accepts NodeRefs (`handle`, `name`, or JSON-Pointer `path`), validates every operation before editing, rejects hierarchy/name conflicts, supports mutation-only stale-sequence guard