Houdini MCP

Run several Houdini tools in one call. Use it to build a network: many nodes, their wires and their parameters go in one round trip and one undo group, and a person can undo the whole thing with one keystroke. Do not use it when a later step needs to read what an earlier step made. The list runs without you in the middle, so nothing can branch on a result. A failed batch changes nothing. Every step is checked before any step runs, and a step with a wrong argument stops the batch. A step that fails as it runs stops the list, and the steps before it are undone. A step whose item failed is a failed step, and so is a parameter write that did not apply. The error names the index of the step and its error. Returns JSON with one result for each operation, in the order of the operations, and the picture of every capture step. A batch that works cooks the display node of each SOP network that it touched: `check` gives its point and primitive counts, and the touched nodes that have errors. Read it before you build on the result. A capture step with no `output` writes to a file of its own, so one batch can hold several captures.

Make a picture of the scene, or of the network editor, and look at it. Modes: viewport, quad, camera, flipbook, sheet, movie, network. Use it to confirm your own work: numbers in a node do not tell you that the result looks wrong. Use it before you report that a task is done. Do not use it for a final picture: render does that through a ROP. The view goes back to where the user left it when the picture is written. Nothing here changes the scene for good. mode: "viewport" — the viewport as it is now. "quad" — four pictures: top, front, right and perspective. "camera" — through the camera node at `camera`. "flipbook" — a sequence over `frame_range` [start, end]. Returns the path of the files, not a picture. "sheet" — `node` at many frames on one picture, a tile for each frame with its number, all from one camera that does not move. Frames: `frames`, or `count` frames from `start` (the current frame) at `step` (1). A step over 2 hides movement and gives a warning: look at a short range at step 1. `reference` is a picture to put first, to compare. `columns`, `tile_width` set the grid. The frames cook in order, forward, and the result gives the cook seconds of each one. `azimuths` (a list of angles) draws each frame from each angle: one frame and 8 angles is a turntable. `bounds` [xmin, ymin, zmin, xmax, ymax, zmax] is the box to frame, for example the hands only. "movie" — `node` over `frames` or `frame_range` (the playbar range) as an MP4 at `fps`, `resolution` [width] wide. Returns the path; open it in a player. "network" — the network editor as the user sees it: names, wires, dots, comments. `node` is the network to show, `paths` the ite…

Change how nodes feed each other. Modes: connect, disconnect, reorder. Use it after node_edit made the nodes. A list of wires goes in one undo group and one round trip. Do not use it to wire a node that you make now: node_edit mode "create" takes `input_path` and wires it in the same call. Do not use it to read the wires: scene_overview mode "network" lists them. mode: "connect" — src_path feeds dst_path. dst_input_index chooses the input, src_output_index the output. Both count from 0. A wire into an input that has one replaces it. Either end can be a network dot. "disconnect" — path loses the wire on input_index. "reorder" — path takes its inputs in the order input_indices. For several wires, give `items`: for "connect", each item has src_path and dst_path, and can have dst_input_index and src_output_index; for "disconnect", each item has path, and can have input_index. Returns JSON, one line for each wire, with the paths that Houdini used. An input index that the node does not have is reported, not dropped.

Read the Houdini log and the node errors. Use it when something did not do what you expected. A cook error often hides behind an empty result: the geometry has no points, and the reason is here. Do not use it for the errors of nodes that you cook now: cook returns them, with the nodes upstream that failed. scene_overview mode "errors" lists every node with a cook error, without the log. Each call takes the log entries away, so a call returns only what is new since the call before it. Returns JSON.

Force work to happen, and report what the work said and what it cost. Modes: cook, cache_write, cache_clear, sim_step, sim_reset, recook. Use it to run a test: write a few parameters, cook a range of frames, and read the seconds for each frame. That is one call, and it is the loop that every look iteration needs. Do not use it to read the result: geometry_inspect does that, and it cooks the node as well. mode: "cook" — cook the nodes and return the errors, the warnings and the time. `frames` or `frame_range` cooks over more than one frame; the playbar goes back to where it was. "cache_write" — write the file cache of the node. frame_range is [start, end]; without it the node writes its own range. "cache_clear" — remove the cached files of the node. "sim_step" — step a DOP network num_steps frames. "sim_reset" — clear the cache of a simulation, so that the next cook runs it again. It accepts a DOP network and a solver SOP such as a Pyro, FLIP, Vellum or RBD solver. After you change anything inside a solver, reset it: the node gives its old result back with no error and no warning. On a solver SOP it cooks the sources first, cooks the start frame after the reset, and reports the primitives there. It fails when the result is empty while the sources are not: that simulation stays empty on every frame. "recook" — cook again each node at or under `paths` that holds an error or a warning, the deepest first, and say which messages were stale (gone) and which are current. Use it when an error names a cause that the network does not have, such as "Infinite recursion" with no cycle. Cook frames he…

Read the official Houdini documentation. This is the authority on every node, parameter, VEX function and HOM call. Read the page before you use an API that you have not confirmed in this session: names and enum members change between Houdini releases, and a wrong one often fails without a message. Do not answer from memory, and do not read sidefx.com yourself. The pages come from the Houdini install on this machine, so they match the build exactly. The first search on a build indexes it once, which takes a few seconds; the index stays on disk. A page read never waits for it. Give exactly one of `query` (search), `page` (read a page from a hit) or `node` (the page of a node type). A node path is the only input that needs Houdini. Returns markdown for a page, JSON for a search.

Run code in Houdini, with the full `hou` module and no guard. Modes: python, hscript, expression, vex_check, env, job. Use it for what no other tool covers, and to confirm an API in the live session, for example `print(dir(hou.Node))`. The code runs with the rights of the Houdini process: it can write files, delete nodes and quit Houdini. Do not use it to build a network: one batch of node_edit create, connect and parm_set is also one round trip, and each step reports its errors. `hou.Node.inputs()` skips network dots and gives the node behind them; use `inputConnections()` and `inputItem()` for the real wiring before you rewire or delete. Prefer a named tool when one exists. A write in code to a parameter that holds an expression, that is disabled or hidden, or whose range clamps the value changes nothing, and a write to a channel reference changes another node. The answer lists each such write in `write_warnings`; read it. If you write the same script twice, the named tool for it is missing: say so in the feedback at the end of the session. mode: "python" — run `source` as Python. Returns stdout and stderr, and keeps them when the script raises. Print what you want to see: the value of the last line does not come back. "hscript" — run `source` as an HScript command. "expression" — evaluate `source` as an expression. `language` is "hscript" or "python". "vex_check" — compile `source` as VEX and report the errors. Nothing runs. "env" — read the Houdini variable `name`, for example "HIP". "job" — the state of the background job `job`: running, with what it printed so far, or done, with its result. `wait` waits for the end, up to that many seconds. Use `file` for a script that you run again with other values. Houdini answers nothing while a script runs: for long work, such as a sweep, use `background` wi…

Read the geometry that a node produces. This cooks the node. Modes: summary, points, prims, attrib, groups, group_members, bbox, intrinsics, nearest, skeleton, compare, try, volume_stats, volume_voxels, volume_sample, volume_compare, image, volume, export, fingerprint, stretch, inside, crossings. Use it to confirm that a node made what you expected: the point count, an attribute that a wrangle wrote, the shape of a volume, the size of the bounding box. Do not use it to read parameters: node_inspect does that. mode: "summary" — counts, attributes, groups, volumes, bounds. Start here. An empty result carries the errors and the warnings of the node, which is where the reason is. "points" — `count` points from `start`, with `attribs`. "prims" — `count` primitives from `start`. "attrib" — the values of `attrib_name` on `attrib_class` ("point", "prim", "vertex", "detail"): min, max and mean of each component over every element, and `limit` (10) values from `start`. A vector attribute keeps its shape. unique=True returns each value that occurs and how many elements carry it, which is how you find the pieces in a geometry. "groups" — the groups of `group_type`. "group_members" — the members of `group_name`. "bbox" — the bounding box. "intrinsics" — the intrinsic values of primitive `prim_index`. "nearest" — the point nearest to `position`, for example [0,1,0]. "skeleton" — a KineFX skeleton: each joint with its name, its parent and its transform. `pattern` keeps the names that match ("|" between alternatives, * as a wildcard). A KineFX import holds the skeletons on output 1 and 2: give `outpu…

Read and change Houdini digital assets. Modes: list, get, install, uninstall, reload, update, create, sections, section_get, section_set. Use it when a node type comes from a .hda file: to find the file, to load a new one, or to read the scripts and the help inside it. Do not use it for the parameters of one node in the scene: node_inspect does that. mode: "list" — the installed assets. `category` filters, for example "Sop". "get" — the definition of `node_type`: the file, the version and the tools. "install" — load the .hda file at `file_path` into the session. "uninstall" — unload the .hda file at `file_path`. "reload" — read the .hda file at `file_path` again, after an edit on disk. "update" — save the node at `node_path` back into its asset. "create" — make an asset from the subnet at `node_path`, with `name`, `label` and `file_path`. "sections" — the section names inside `node_type`. "section_get" — the text of `section_name`, for example "PythonModule". "section_set" — write `content` into `section_name`. Returns JSON. "install" and "uninstall" change every node of that type in the session.

Change the nodes in a network. One item, or a list in one undo group. Modes: create, delete, copy, move, rename, flags, color, layout, insert, place_chain, wrangle, material, assign_material, take, current_network, note, box, split. Use it to build a network. Then use parm_set for the values, and connect for the wires. Do not compute positions: create with input_path, insert and place_chain place the nodes the way the user lays out a graph, move a node of the user only down to make room, and return every node that moved with its old and new position. Each returns the layout faults it sees. Do not use it to set parameters: parm_set does that, and it reports a write that had no effect. mode, and the arguments that each mode reads: "create" — node_type, parent_path, name, position, parameters, input_path. context selects the network kind: "sop" (default), "cop", "chop", "lop", "material_network". "delete" — path or paths: nodes, dots, sticky notes or network boxes. A node that still feeds a node outside paths is refused, with the list of its readers, unless force=true. "copy" — paths (or path), destination_path, suffix, names. Copies a set of nodes with the wires between them; a wire from outside the set goes to the same node. suffix is added to each name, or names maps a source path or name to a new name. Returns `copies`, each source path with the path of its copy: use that map, never the order of a list. Without destination_path the copies go to the right of the sources. "move" — path with destination_path to put it in another networ…

Read one node, or a list of nodes, without changing anything. Modes: info, parms, schema, changed, names, expression, keyframes, code, cook_chain, explain, material, image, channels, simulation, render_settings, cache, time_dependency, validate, layout, readers. Use it before you write: to confirm a parameter name, to see whether a parameter carries an expression, and to read what a node reports after a cook. Do not use it to list a network: scene_overview does that. mode: "info" — type, inputs, outputs, flags, changed parameters. "parms" — every parameter, or one parameter when you give `parm`. The result says whether the value comes from an expression. "schema" — the parameter templates: types, ranges, menus. Read this before you write a menu parameter. "changed" — only the parameters that a person set: not at the default, or with an expression or keys. Folders, labels, buttons and hidden fields are left out, and a ramp is one entry with its keys. "names" — the names of the parameters, and nothing else. Read this first when you do not know the name to write. "expression" — the expression on `parm`, and its language. "keyframes" — the keys on `parm`. "code" — the VEX snippet in a wrangle node. "cook_chain" — what this node cooks from, upstream. "explain" — a short account of what the node does here. "material" — the shader parameters of a material node. "image" — the COP node: resolution, planes, data type. "channels" — CHOP channels. `channel`, `start` and `end` read the samples of one channel. "simulation" — the DOP network. `object_name` reads one object, with `field_name` one fie…

Write parameter values, or press a button. One write, or a list in one undo group. Modes: value, press, expression, keyframe, keyframes, delete_keyframe, revert, lock, link, spare, render_settings, chop_export, snapshot, restore, diff. Use it after node_inspect has confirmed the parameter name and the type. A write can be accepted and change nothing, and Houdini says nothing. This tool looks for all six causes and names the one it found: - the parameter carries an expression, which still decides the value; - the parameter is animated, so the value became a new key; - the parameter is locked; - another parameter disables or hides it, so the cook does not read it; - a strict range clamped the value; - the parameter reads another node through a channel reference, so the write would change that other node. It is refused; give `follow_reference=true` to write the node at the other end. Read `warnings` and `not_applied` in the result before you report success. mode, and the arguments that each mode reads: "value" — path, parm, value. Or path and parameters, a dictionary of several names and values. A menu takes its token, for example "custom". A bit-field menu takes a token or a list of them. "press" — path, parm: press a button, for example Save to Disk on a File Cache, Reload on a File SOP, or Resimulate on a solver. The result holds the errors and the warnings of the node after the press, because work that a button starts fails later and in silence. "expression" — path, parm, expression, language ("hscript" or "python"). "keyframe" — path, parm, frame, value. "keyframes" — path, parm, keyframes: a list of {frame, value}. "delete_keyframe" — path, parm, frame. "revert"…

Cook a TOP network, and read what its work items did. Modes: status, workitems, cook, dirty, cancel. Use it for a TOP network only. A TOP node does not cook like a SOP: it makes work items, and each item runs on its own. For a SOP or a DOP, use cook. For a ROP, use render. mode: "status" — the counts for each state, and whether a cook runs now. "workitems" — the items. `state` filters, for example "failed". "cook" — start the cook. The call comes back at once; read "status" after it to follow the work. "dirty" — mark the node dirty. `dirty_all` also removes the outputs on disk. "cancel" — stop the cook that runs now. Returns JSON. A failed item holds the command and the log path: read those before you change the network.

Read or set the time of the session. Modes: get, frame, range, playback, play. Use it before you read geometry that changes over time: a SOP cooks at the current frame, so the frame decides what you see. Do not use it only to read another frame: geometry_inspect, node_inspect and stage_inspect take `frames` and put the playbar back after. A frame that you set here stays for the person and for every later call, and "range" also changes what a flipbook covers, and a ROP whose range follows $FSTART and $FEND. mode: "get" — the current frame and time. "frame" — go to `frame`. "range" — set the scene frame range to `start` and `end`. "playback" — set the playback range inside the scene range. "play" — `action` is "play", "stop", "next", "previous", "start" or "end". Playback needs a GUI. Returns JSON.

Start a render, read its settings, or watch it run. Modes: start, progress, settings, create, watch, stats, compare. Use it for a final picture through a ROP node. For a fast look at the viewport, use capture instead: it is much quicker. mode: "start" — render the ROP at `path`. `frame_range` is [start, end]; without it the node renders its own range. `output_path` and `res_scale` hold for this render only: the ROP keeps the output and the size of the user. Use them for test renders. `wait=true` returns when every image is complete (husk ended; up to about 28 minutes), with the render stats of the last one. Without wait, husk can go on after the call. "progress" — what the ROP reports about the render. "settings" — the output file, the camera, the resolution and the range of the ROP; the render delegate that really runs (`engine` cpu or xpu, and `engine_from`: the ROP renderer, else husk:default_delegate on the render settings prim); a warning when a Karma settings node says another engine; and the changed Karma settings, split into the ones that engine reads and the ones it ignores, with the reason. Karma XPU shows the CPU Quality controls and ignores them; its Limits tab counts. parm_set and execute warn on a write that the engine of the node ignores. "create" — make a ROP of `render_type` ("opengl", "karma", "mantra", "ifd", …) named `name` under `parent_path`. "watch" — count the husk and mantra processes on this machine, and say whether the file at `output_path` is there and how big it is. This mode does not need Houdini, so it also works while Houdini is busy with the render.…

Read, save or load the scene file, or step its undo history. Modes: info, save, load, undo, redo. Use "save" before a change that is hard to undo, and use "info" to learn whether the session holds work that is not saved. mode: "info" — the file name, the frame range, the counts, and whether the session has changes that are not saved. "save" — save to `path`, or over the open file when `path` is empty. "load" — open the .hip file at `path`. Everything in the session goes away, and the undo history with it. "undo" — undo `count` steps. Each call of a tool that changes the scene is one step. A batch is one step, except a batch with a step that waits (capture, render): there each step is one. Returns the labels it undid and the next ones. "redo" — redo `count` steps. Returns JSON.

List what the scene holds. Start here, before you touch a node. Modes: scene, network, children, search, node_types, errors, materials, lights, takes, caches, render_nodes, viewports, changes. Use it to find a node path, to see the shape of a network, or to learn which node types this Houdini has. Do not use it to read one node in detail: node_inspect does that. Do not use it to read geometry: geometry_inspect does that. mode: "scene" — file, frame range, counts, and the top of the tree. "network" — the children of one network by name, with their wires, flags and dots. Each input names the dot it comes through, then the node behind the dot. `pattern` and `node_type` keep some nodes; compact=True gives only the wires. "children" — the children of `path`. recursive=True walks down. "search" — nodes whose name matches `pattern`, under `path`. node_type filters by type name. "node_types" — the node types this Houdini has, for one `category` such as "Sop", "Object", "Lop", "Driver". `pattern` keeps the names or labels that match. "errors" — every node under `path` that has a cook error. "materials" — the materials in `path` (default /mat) and the types. "lights" — the lights on the USD stage of the LOP node `path`. "takes" — the takes, and which take is current. "caches" — file caches under `path` and their state on disk. "render_nodes" — the ROP nodes in /out. "viewports" — the panes, and what the scene viewer shows. "changes" — what the user changed in the network `path` since your last call: nodes added, deleted, renamed or moved, wires, flags and parameter values. Your own changes are not listed. The first call starts to watc…

Read the node selection, or set it. Use it to see what the person works on before you change the scene, and to show them your result when you are done. Do not use it to find nodes: scene_overview mode "search" does that. A path is the full path of a node, for example "/obj/geo1/mountain1". A path that is not a node stops the call with an error, and the selection stays as it was. Returns JSON with the selected paths.

Report the Houdini sessions, choose one, or start, stop or interrupt one. Actions: status, list, attach, detach, interrupt, start, start_gui, stop. Use it first when a tool says that Houdini is not reachable, and use it to learn the Houdini version before you use an API that changed between releases. Several Houdini sessions can listen at the same time: the graphical one that holds the work of the user, and a headless one for your own tests. Every tool result names the session that answered, in `_session`. Read that line when a scene looks empty or wrong: an empty scene is usually the wrong session, not a lost scene. Do not use it to read the scene: scene_overview does that. action: "status" — the session that the bridge talks to now, the other sessions, and the port. Starts nothing, and always answers. "list" — every Houdini that runs, with its version, its process id, its .hip file, whether it has a window and whether it answers; and the Houdini versions installed. "attach" — send every later command to the Houdini on `port`. Use it when "list" shows more than one. "detach" — forget the attached port and let the bridge choose again. "interrupt" — stop the call that runs now in the attached Houdini, or in the one on `port`: a script past its budget, a loop that will not end. Houdini answers again after it. A single long cook does not return to Python; then, in a Houdini with a window on Windows, it sends Escape to the window, as the user would. A stopped simulation keeps a partial cache. "start" — start a headless Houdini (hython) and attach to it. `version` chooses the release, for example "21.0" or "21.0.829"; without it, the version of the Houdini window that runs. A…

Read the USD stage at a LOP node. This cooks the node. Modes: stage, prims, prim, search, layer, attribute, composition, variants, stats, modified, lights, transform. Use it in a Solaris (LOP) network to see the prims, the layers and the composition that a node produces. Do not use it for SOP geometry: geometry_inspect does that. mode: "stage" — the stage: prim count, layers, the default prim. "prims" — the prim tree from `root_prim`, `max_depth` deep. "prim" — one prim at `prim_path`. include_attrs=True adds its attributes. "search" — prims whose path matches `pattern`, filtered by `type_name` such as "Mesh" or "SphereLight". "layer" — the layer stack, and the layer at `layer_index`. "attribute" — the value of `attr_name` on `prim_path`. "composition" — where the opinions on `prim_path` come from: each layer of its prim stack, strongest first, with the node that wrote it (the SOP behind an op: layer) and its references and payloads. "variants" — the variant sets on `prim_path` and the selection. "stats" — counts under `prim_path`. "modified" — the last `count` prims that this node changed. Use it to see what one LOP did. "lights" — the lights on the stage. "transform" — where `prim_path` is in the world: translate, rotate and scale composed through every parent. With `frames`, the path of a moving prim. Returns JSON.