/3dsmax-mcp-dev

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

3ds Max MCP — Agent Guide

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: use **MCP Claim This Max** in the target window so tools hit the right session.

Tool Choice

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

• `overview` | `filter` | `class` | `property` | `selection` | `delta`
• **`get_instances`** / **`get_dependencies`** — instancing and reference graph
• **`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`

Mutation:

• Use object, modifier, material, controller, organization, and viewport tools when they match.
• 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

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` `get_hierarchy` `get_instances` `get_dependencies`

Objects

`get_object_properties` `analyze_node_orientation` `set_object_property` `create_object` `delete_objects` `transform_object` `select_objects` `set_visibility` `clone_objects` `set_parent` `batch_rename_objects`

Modifiers

`add_modifier` `remove_modifier` `set_modifier_state` `set_modifier_property` `collapse_modifier_stack` `make_modifier_unique`

Modeling

• `boolean_operation` — Boolean modifier (BooleanMod): apply union/subtract/intersect/merge/attach operands, list/retune/rename/extract them. Inline `cutters` build scratch primitives in the same call ({name, shape: box|cylinder|sphere, size, pos (bbox center), rot, operation?}) — consumed on apply, zero scene litter; `repeat` {count, axis, spacing} arrays every cutter (`vent_1..N`) for vents/ribs/window grids. Recipes: hole = Z-axis cylinder cutter overshooting both faces (rot to orient); slot = box cutter; panel line = cutter + `operation_option="imprint"`.
• `draw_spline` — spline shapes from world-space point lists; knot readback and editing, holes via add_spline, renderable thickness
• `edit_vertices` — Editable_Poly verts in world space: get (filtered), move (soft falloff), set, conform to a spline or ray-projected onto geometry
• Curved-form recipe: `draw_spline` the reference profile → Lathe/Extrude/Bevel_Profile/Sweep via `add_modifier` → refine with `set_knots` or `edit_vertices conform`

Materials

• Create + assign: `assign_material`, `create_material_from_textures`, `smart_import`, `palette_laydown`
• Edit: `set_material_property`, `set_material_properties`
• Inspect: `get_material_slots`, `get_materials`, `get_material_library`
• Scratch libraries: `backup_material_library` saves `currentMaterialLibrary` / `meditMaterials` to `.mat`
• Multi/Sub: `set_sub_material`
• Textures: `create_texture_map`, `set_texture_map_properties`
• Dual pipeline: `create_shell_material`, `replace_material`, `batch_replace_materials`
• OSL: `write_osl_shader`

Material notes

• `create_material_from_textures` and `smart_import` default to **OpenPBR**. Pass `material_class` for Physical, Arnold, Redshift, V-Ray, MaterialX, Octane, etc. (see tool tripback `hint.renderers`).
• `create_shell_material` wraps two scene materials in `Shell_Material` (render slot 0, export/viewport slot 1), or builds from `texture_folder` with `render_material_class` / `export_material_class`. Shell is a container, not a renderer.

Viewport

• Fast: `capture_viewport`
• Multi-angle grid: `capture_multi_view`
• Fullscreen: `capture_screen` (requires `enabled=True`)

External .max files (no scene load)

• `inspect_max_file`, `search_max_files`, `merge_from_file`, `batch_file_info`

Plugin discovery

• `discover_plugin_surface`, `get_plugin_manifest`, `refresh_plugin_manifest`
• `inspect_plugin_class`, `inspect_plugin_constructor`, `inspect_plugin_instance`
• MCP resources: `resource://3dsmax-mcp/plugins/{name}/manifest|guide|recipes|gotchas`

tyFlow

• Create: `create_tyflow`, `create_tyflow_preset`
• Inspect: `get_tyflow_info` (`include_operator_properties` for deep readback)
• Edit: `modify_tyflow_operator`, `set_tyflow_shape`, `set_tyflow_physx`, `add_tyflow_collision`
• Simulate: `reset_tyflow_simulation`, `get_tyflow_particle_count`, `get_tyflow_particles`

For tyFlow graph work (event/operator topology, wiring, transactional edits, operator discovery, per-event census), read [tyflow-graphs.md](tyflow-graphs.md) completely before acting. It covers `get_tyflow_graph`, `tyflow_apply_p