Skip to content

TOOLS.md

Latest commit

 

History

History
343 lines (240 loc) · 34.2 KB

TOOLS.md

File metadata and controls

343 lines (240 loc) · 34.2 KB
Raw

KeyShot MCP Tool Reference

Generated from src/tools/catalog.ts. Do not edit this file by hand.

KeyShot MCP exposes 19 tools. All tools return JSON text and structured content using the common result schema.

Diagnostics

keyshot_status

Check KeyShot MCP status

Diagnose the local installation, output access, presets, bridge files, and a minimal KeyShot headless startup without modifying a user scene.

Safety: read-only; non-destructive; local only.

Parameters: none.

Rendering

keyshot_product_render

Prepare and render a product

Run a complete product workflow in one headless process: open or import, assign materials, configure camera and environment, save a scene copy, and render one or all cameras.

Safety: writes output; potentially destructive; local only.

Parameter Required Type Description
modelPath No string Absolute path to a model to import. Provide exactly one modelPath or scenePath.
scenePath No string Absolute path to an existing KeyShot scene. Provide exactly one scenePath or modelPath.
baseScenePath No string Optional KeyShot base scene used only when modelPath is provided.
outputScenePath No string Destination for the prepared scene. A safe numbered name is generated when omitted.
renderMode No single / allCameras Render one active or named camera, or discover and render every saved camera. Defaults to single.
outputPath No string Single-mode image destination. Invalid with allCameras mode; a safe name is generated when omitted.
outputDir No string All-cameras output directory. Invalid with single mode; a safe directory is generated when omitted.
centerGeometry No boolean Center imported geometry. Applies only to modelPath sources and defaults to true for new models.
snapToGround No boolean Place imported geometry on the ground. Applies only to modelPath sources and defaults to true for new models.
adjustCameraLookAt No boolean Retarget the camera after model import. Applies only to modelPath sources and defaults to true for new models.
adjustEnvironment No boolean Adjust the environment after model import. Applies only to modelPath sources and defaults to true for new models.
materialAssignments No object[] Object-specific material changes applied before camera and environment setup.
cameraPresetName No string Configured camera preset to apply. Cannot be combined with a custom position/lookAt pair.
cameraName No string Camera to create, update, or activate. New model workflows default to Product Hero.
position No tuple Camera position [x, y, z]. Must be provided together with lookAt.
lookAt No tuple Camera target [x, y, z]. Must be provided together with position.
up No tuple Optional camera up direction [x, y, z]. Requires position and lookAt.
distance No number Positive KeyShot camera distance applied after the transform or preset.
fieldOfView No number Camera field of view in degrees, greater than 0 and less than 180. Cannot be combined with focalLength.
focalLength No number Camera focal length from 5 to 200 mm. Cannot be combined with fieldOfView.
environmentName No string Environment name from the KeyShot library. Cannot be combined with environmentPath.
environmentPath No string Absolute path to a local KeyShot environment file. Cannot be combined with environmentName.
brightness No number Positive brightness multiplier for the active environment.
rotation No number Environment rotation in degrees, from 0 inclusive to 360 exclusive.
width No number Render width in pixels. Overrides the selected quality preset when provided.
height No number Render height in pixels. Overrides the selected quality preset when provided.
samples No number Maximum render samples. Cannot be combined with maxTimeSeconds and overrides preset sampling when provided.
maxTimeSeconds No number Maximum render time in seconds. Selects time-based rendering and cannot be combined with samples.
format No png / jpg / jpeg / tif / tiff / exr Output image format. Defaults to PNG when omitted.
qualityPreset No preview / standard / final Render quality preset: preview (960x540, 16 samples), standard (1920x1080, 64 samples), or final (3840x2160, 256 samples).
overwrite No boolean Allow replacement of explicitly selected output files. Defaults to false.
continueOnError No boolean In allCameras mode, continue after one camera fails. Defaults to true.

keyshot_preview_render

Render an Agent-visible preview

Render a bounded PNG preview from an existing scene and return it directly as MCP image content. Temporary previews are deleted after embedding; an optional safe output path preserves a copy.

Safety: read-only; non-destructive; local only.

Parameter Required Type Description
scenePath Yes string Absolute path to an existing KeyShot scene file to open. Input files may be outside the configured output directory.
camera No string Optional saved camera name to activate for the preview. Omit to use the scene's active camera.
width No number Preview width in pixels. Defaults to 960; allowed range is 64 to 1920.
height No number Preview height in pixels. Defaults to 540; allowed range is 64 to 1080.
samples No number Preview render samples. Defaults to 16 unless maxTimeSeconds is provided; maximum is 64.
maxTimeSeconds No number Time-based preview limit in seconds. Replaces the default sample mode and cannot be combined with an explicit samples value; maximum is 60.
outputPath No string Optional .png destination inside KEYSHOT_OUTPUT_DIR. Existing files are never overwritten. When omitted, a temporary preview is embedded and deleted.

keyshot_render

Render one KeyShot view

Render the active or a named camera from an existing scene to an image file.

Safety: writes output; potentially destructive; local only.

Parameter Required Type Description
scenePath Yes string Absolute path to an existing KeyShot scene file to open. Input files may be outside the configured output directory.
outputPath No string Destination image path. When omitted, a PNG name is generated inside KEYSHOT_OUTPUT_DIR.
width No number Render width in pixels. Overrides the selected quality preset when provided.
height No number Render height in pixels. Overrides the selected quality preset when provided.
samples No number Maximum render samples. Cannot be combined with maxTimeSeconds and overrides preset sampling when provided.
maxTimeSeconds No number Maximum render time in seconds. Selects time-based rendering and cannot be combined with samples.
camera No string Optional saved camera name to activate before rendering. Omit to use the scene's active camera.
format No png / jpg / jpeg / tif / tiff / exr Output image format. Defaults to PNG when omitted.
qualityPreset No preview / standard / final Render quality preset: preview (960x540, 16 samples), standard (1920x1080, 64 samples), or final (3840x2160, 256 samples).

keyshot_render_queue

Run a sequential render queue

Render independent scene and camera jobs sequentially so KeyShot processes do not compete for a license or output files.

Safety: writes output; potentially destructive; local only.

Parameter Required Type Description
jobs Yes object[] Render jobs executed sequentially to avoid KeyShot license and output conflicts.
continueOnError No boolean Continue with later jobs after a failure. Defaults to false.

keyshot_batch_render

Render selected cameras

Render an explicit list of saved cameras from one scene into an output directory.

Safety: writes output; potentially destructive; local only.

Parameter Required Type Description
scenePath Yes string Absolute path to an existing KeyShot scene file to open. Input files may be outside the configured output directory.
outputDir Yes string Directory for generated render files. Relative paths resolve inside KEYSHOT_OUTPUT_DIR; external paths are rejected by default.
cameras Yes string[] Saved camera names to render in order. Use keyshot_list_cameras first when names are unknown.
width No number Render width in pixels. Overrides the selected quality preset when provided.
height No number Render height in pixels. Overrides the selected quality preset when provided.
samples No number Maximum render samples. Cannot be combined with maxTimeSeconds and overrides preset sampling when provided.
maxTimeSeconds No number Maximum render time in seconds. Selects time-based rendering and cannot be combined with samples.
format No png / jpg / jpeg / tif / tiff / exr Output image format. Defaults to PNG when omitted.
qualityPreset No preview / standard / final Render quality preset: preview (960x540, 16 samples), standard (1920x1080, 64 samples), or final (3840x2160, 256 samples).
overwrite No boolean Whether existing image files may be replaced. Defaults to false.

keyshot_render_all_cameras

Render all scene cameras

Discover every saved camera and render each view in one headless process with collision-safe file names and per-camera results.

Safety: writes output; potentially destructive; local only.

Parameter Required Type Description
scenePath Yes string Absolute path to an existing KeyShot scene file to open. Input files may be outside the configured output directory.
outputDir Yes string Directory for generated render files. Relative paths resolve inside KEYSHOT_OUTPUT_DIR; external paths are rejected by default.
width No number Render width in pixels. Overrides the selected quality preset when provided.
height No number Render height in pixels. Overrides the selected quality preset when provided.
samples No number Maximum render samples. Cannot be combined with maxTimeSeconds and overrides preset sampling when provided.
maxTimeSeconds No number Maximum render time in seconds. Selects time-based rendering and cannot be combined with samples.
format No png / jpg / jpeg / tif / tiff / exr Output image format. Defaults to PNG when omitted.
qualityPreset No preview / standard / final Render quality preset: preview (960x540, 16 samples), standard (1920x1080, 64 samples), or final (3840x2160, 256 samples).
overwrite No boolean Whether existing image files may be replaced. Defaults to false.
continueOnError No boolean Continue rendering remaining cameras after one camera fails. Defaults to true.

Inspection

keyshot_inspect_scene

Inspect a KeyShot scene

Open a scene read-only and return metadata, objects, cameras, material assignments, model sets, and external references.

Safety: read-only; non-destructive; local only.

Parameter Required Type Description
scenePath Yes string Absolute path to an existing KeyShot scene file to open. Input files may be outside the configured output directory.

keyshot_list_cameras

List scene cameras

Return saved camera names without saving changes. Use this before selected-camera rendering when names are unknown.

Safety: read-only; non-destructive; local only.

Parameter Required Type Description
scenePath Yes string Absolute path to an existing KeyShot scene file to open. Input files may be outside the configured output directory.

keyshot_sync_saved_scene

Sync the latest saved KeyShot scene

Find a saved .bip file (or the newest .bip in one folder), detect whether it changed, copy it to a collision-safe output path, and optionally return an Agent-visible preview. This is the stable alternative to unsupported persistent GUI control.

Safety: writes output; potentially destructive; local only.

Parameter Required Type Description
sourcePath Yes string Absolute path to a saved .bip scene or a directory whose newest .bip scene should be synchronized. Directories are searched only at their top level.
previousFingerprint No string Optional fingerprint returned by an earlier sync. When it still matches, no copy or preview is created.
outputScenePath No string Optional destination for the synchronized .bip copy inside KEYSHOT_OUTPUT_DIR. Existing explicit paths are never overwritten; when omitted, a collision-safe name is generated.
includePreview No boolean Whether to render and embed a temporary PNG from the synchronized copy. Defaults to true.
camera No string Optional saved camera name for the embedded preview. Omit to use the scene's active camera.
width No number Preview width in pixels. Defaults to 960; allowed range is 64 to 1920.
height No number Preview height in pixels. Defaults to 540; allowed range is 64 to 1080.
samples No number Preview render samples. Defaults to 16 unless maxTimeSeconds is provided; maximum is 64.
maxTimeSeconds No number Time-based preview limit in seconds. Replaces the default sample mode and cannot be combined with an explicit samples value; maximum is 60.

Scene editing

keyshot_import_model

Import a model into KeyShot

Import a supported local model into an empty or base scene, apply requested composition options, and save a new scene.

Safety: writes output; potentially destructive; local only.

Parameter Required Type Description
modelPath Yes string Absolute path to a model file supported by KeyShot, such as OBJ, FBX, STL, or glTF.
baseScenePath No string Optional existing KeyShot scene to use as the import base. Omit to start from an empty scene.
outputScenePath Yes string Destination path for the saved KeyShot scene. The path must stay inside KEYSHOT_OUTPUT_DIR unless external outputs are explicitly enabled.
centerGeometry No boolean Ask KeyShot to center imported geometry during import when supported.
snapToGround No boolean Ask KeyShot to place imported geometry on the ground plane when supported.
adjustCameraLookAt No boolean Ask KeyShot to retarget the active camera to the imported geometry when supported.
adjustEnvironment No boolean Ask KeyShot to adjust the environment to the imported geometry when supported.

keyshot_set_environment

Set the KeyShot environment

Select an environment by library name or local file, optionally change brightness and rotation, and save the edited scene.

Safety: writes output; potentially destructive; local only.

Parameter Required Type Description
scenePath Yes string Absolute path to an existing KeyShot scene file to open. Input files may be outside the configured output directory.
environmentName No string Environment name from the KeyShot library. Cannot be combined with environmentPath.
environmentPath No string Absolute path to a local KeyShot environment file. Cannot be combined with environmentName.
brightness No number Positive brightness multiplier for the active environment.
rotation No number Environment rotation in degrees, from 0 inclusive to 360 exclusive.
outputScenePath Yes string Destination path for the saved KeyShot scene. The path must stay inside KEYSHOT_OUTPUT_DIR unless external outputs are explicitly enabled.

keyshot_save_scene

Save a KeyShot scene copy

Open an existing scene and save a copy to a requested path inside the configured safe output directory.

Safety: writes output; potentially destructive; local only.

Parameter Required Type Description
scenePath Yes string Absolute path to an existing KeyShot scene file to open. Input files may be outside the configured output directory.
outputScenePath Yes string Destination path for the saved KeyShot scene. The path must stay inside KEYSHOT_OUTPUT_DIR unless external outputs are explicitly enabled.

Materials

keyshot_apply_material

Apply a KeyShot material

Apply a KeyShot library material or local material file to a specific object, then save the edited scene.

Safety: writes output; potentially destructive; local only.

Parameter Required Type Description
scenePath Yes string Absolute path to an existing KeyShot scene file to open. Input files may be outside the configured output directory.
objectName No string Scene object name to modify. Provide either objectName or the more specific objectPath.
objectPath No string Full scene-tree path of the object to modify. Use this instead of objectName when names are duplicated.
materialName No string Material name from the local KeyShot library. Provide either materialName or materialPath.
materialPath No string Absolute path to a local KeyShot material file. Provide either materialPath or materialName.
outputScenePath Yes string Destination path for the saved KeyShot scene. The path must stay inside KEYSHOT_OUTPUT_DIR unless external outputs are explicitly enabled.

keyshot_list_material_presets

List material presets

Read the configured local material preset JSON and return valid preset names and material sources without opening KeyShot.

Safety: read-only; non-destructive; local only.

Parameters: none.

keyshot_apply_material_preset

Apply a material preset

Resolve a configured material preset, apply it to one scene object, and save a new scene.

Safety: writes output; potentially destructive; local only.

Parameter Required Type Description
scenePath Yes string Absolute path to an existing KeyShot scene file to open. Input files may be outside the configured output directory.
presetName Yes string Case-insensitive material preset name returned by keyshot_list_material_presets.
objectName No string Scene object name to modify. Provide either objectName or objectPath.
objectPath No string Full scene-tree path to modify. Prefer this when object names are duplicated.
outputScenePath Yes string Destination path for the saved KeyShot scene. The path must stay inside KEYSHOT_OUTPUT_DIR unless external outputs are explicitly enabled.

Cameras

keyshot_set_camera

Set a KeyShot camera

Create or update a named camera using position, target, distance, field of view, or focal length, then save the edited scene.

Safety: writes output; potentially destructive; local only.

Parameter Required Type Description
scenePath Yes string Absolute path to an existing KeyShot scene file to open. Input files may be outside the configured output directory.
cameraName No string Saved camera to update, or the name to use when creating a camera.
position No tuple Camera position [x, y, z]. Must be provided together with lookAt.
lookAt No tuple Camera target [x, y, z]. Must be provided together with position.
up No tuple Optional camera up direction [x, y, z]. Requires position and lookAt.
distance No number Positive KeyShot camera distance.
fieldOfView No number Field of view in degrees, greater than 0 and less than 180. Cannot be combined with focalLength.
focalLength No number Focal length from 5 to 200 mm. Cannot be combined with fieldOfView.
outputScenePath Yes string Destination path for the saved KeyShot scene. The path must stay inside KEYSHOT_OUTPUT_DIR unless external outputs are explicitly enabled.

keyshot_list_camera_presets

List camera presets

Read the configured camera preset JSON and return valid standard or absolute camera presets without opening KeyShot.

Safety: read-only; non-destructive; local only.

Parameters: none.

keyshot_apply_camera_preset

Apply a camera preset

Create or update a saved camera from a configured standard-view or absolute camera preset, then save the edited scene.

Safety: writes output; potentially destructive; local only.

Parameter Required Type Description
scenePath Yes string Absolute path to an existing KeyShot scene file to open. Input files may be outside the configured output directory.
presetName Yes string Case-insensitive camera preset name returned by keyshot_list_camera_presets.
cameraName No string Optional saved camera name. Defaults to the preset name.
outputScenePath Yes string Destination path for the saved KeyShot scene. The path must stay inside KEYSHOT_OUTPUT_DIR unless external outputs are explicitly enabled.