Skip to content

scene

scene

MCP tool wrappers for Houdini scene operations.

Each tool delegates to the corresponding handler running inside Houdini via the HTTP bridge.

Functions:

Name Description
export_file

Export a node's output to a file on disk, and report whether it landed.
get_context_info

Get information about a Houdini network context.
get_houdini_connection_status

Check the MCP-to-Houdini bridge without raising on disconnect.
get_scene_info

Get information about the current Houdini scene.
import_file

Import a geometry, USD, or Alembic file into the scene.
load_scene

Open a Houdini hip file, or merge it — or named nodes from it — into
new_scene

Create a new empty Houdini scene.
redo

Redo the last undone change(s) in Houdini.
save_scene

Save the current Houdini scene to disk.
undo

Undo the last change(s) made in Houdini.

Classes

Functions:

export_file async 

export_file(
    ctx: Context,
    node_path: str,
    file_path: str,
    frame_range: list[float] | None = None,
) -> dict

Export a node's output to a file on disk, and report whether it landed.

SOPs are saved directly, LOPs export their USD stage, and a /out ROP is pointed at file_path and executed (its own output path is restored afterwards). Reports wrote_files, so success: True means a file appeared or changed -- not merely that the call returned. A frame_range writes name.0001.ext per frame and leaves the playbar where it was.

Parameters:

Name Type Description Default
node_path
str

Path to the node to export.

 required
file_path
str

Destination file path. For a ROP this overrides its output parameter for the duration of the export.

 required
frame_range
list[float] | None

Frame range as [start, end] or [start, end, step].

 None

get_context_info async 

get_context_info(ctx: Context, context: str) -> dict

Get information about a Houdini network context.

Parameters:

Name Type Description Default
context
str

Context path, e.g. "/obj", "/stage", "/out".

 required

get_houdini_connection_status async 

get_houdini_connection_status(ctx: Context) -> dict

Check the MCP-to-Houdini bridge without raising on disconnect.

Returns structured connection diagnostics, including the configured bridge URL and Houdini health payload when reachable, and sessions: every Houdini serving the plugin (port, pid, version), the one in use marked current. connect_houdini switches; start_houdini starts one. Use this before live viewport workflows when Houdini may have restarted.

get_scene_info async 

get_scene_info(ctx: Context) -> dict

Get information about the current Houdini scene.

import_file async 

import_file(
    ctx: Context,
    file_path: str,
    parent_path: str = "/obj",
    node_name: str | None = None,
) -> dict

Import a geometry, USD, or Alembic file into the scene.

Parameters:

Name Type Description Default
file_path
str

Path to the file to import.

 required
parent_path
str

Network path for the import node.

 '/obj'
node_name
str | None

Name for the created node.

 None

load_scene async 

load_scene(
    ctx: Context,
    file_path: str,
    merge: bool = False,
    node_paths: list[str] | None = None,
    overwrite_on_conflict: bool = False,
) -> dict

Open a Houdini hip file, or merge it — or named nodes from it — into the current scene.

Load warnings (missing assets and the like) come back in warnings. A merge reports what arrived: merged_nodes, conflicts (a node that already exists is merged under a new name, or overwritten in place with overwrite_on_conflict=True) and not_found_in_file. node_paths are absolute (/obj/building_v3) and bring their contents. A merge keeps the scene's set -g variables ($JOB, $POSE) the file would overwrite, named in globals_restored with the file's value and the kept one; variables the file adds are listed in globals_added.

Parameters:

Name Type Description Default
file_path
str

Path to the hip file to open.

 required
merge
bool

Merge into the current scene instead of replacing it.

 False
node_paths
list[str] | None

With merge, the absolute node paths to merge; default everything.

 None
overwrite_on_conflict
bool

With merge, overwrite same-named nodes instead of renaming the merged copy.

 False

new_scene async 

new_scene(ctx: Context, save_current: bool = False) -> dict

Create a new empty Houdini scene.

Parameters:

Name Type Description Default
save_current
bool

Save the current scene before clearing.

 False

redo async 

redo(ctx: Context, steps: int = 1) -> dict

Redo the last undone change(s) in Houdini.

Parameters:

Name Type Description Default
ctx
Context

MCP context.

 required
steps
int

How many steps to redo (default 1).

 1

save_scene async 

save_scene(ctx: Context, file_path: str | None = None) -> dict

Save the current Houdini scene to disk.

Parameters:

Name Type Description Default
file_path
str | None

Destination path; defaults to the current hip file.

 None

undo async 

undo(ctx: Context, steps: int = 1) -> dict

Undo the last change(s) made in Houdini.

Every tool call is one undo step, however many nodes it touched, so one undo reverses one build_network or set_parameters call. Needs a graphical Houdini: hython keeps no undo history.

Parameters:

Name Type Description Default
ctx
Context

MCP context.

 required
steps
int

How many steps to undo (default 1).

 1