# 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. | | `overwrite` | No | boolean | Allow replacing an existing output file. Defaults to false. Input files can never be replaced, even when true. | | `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 | | -------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `overwrite` | No | boolean | Allow replacing an existing output file. Defaults to false. Input files can never be replaced, even when true. | | `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 a saved scene copy, never an input file. Existing files are rejected unless overwrite=true. 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 | | ----------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `overwrite` | No | boolean | Allow replacing an existing output file. Defaults to false. Input files can never be replaced, even when true. | | `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 a saved scene copy, never an input file. Existing files are rejected unless overwrite=true. 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 | | ----------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `overwrite` | No | boolean | Allow replacing an existing output file. Defaults to false. Input files can never be replaced, even when true. | | `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 a saved scene copy, never an input file. Existing files are rejected unless overwrite=true. 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 | | ----------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `overwrite` | No | boolean | Allow replacing an existing output file. Defaults to false. Input files can never be replaced, even when true. | | `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 native single-material KeyShot MTL file, not a Wavefront OBJ companion MTL. Provide either materialPath or materialName. | | `outputScenePath` | Yes | string | Destination path for a saved scene copy, never an input file. Existing files are rejected unless overwrite=true. 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 | | ----------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `overwrite` | No | boolean | Allow replacing an existing output file. Defaults to false. Input files can never be replaced, even when true. | | `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 a saved scene copy, never an input file. Existing files are rejected unless overwrite=true. 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 | | ----------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `overwrite` | No | boolean | Allow replacing an existing output file. Defaults to false. Input files can never be replaced, even when true. | | `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 a saved scene copy, never an input file. Existing files are rejected unless overwrite=true. 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 | | ----------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `overwrite` | No | boolean | Allow replacing an existing output file. Defaults to false. Input files can never be replaced, even when true. | | `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 a saved scene copy, never an input file. Existing files are rejected unless overwrite=true. Must stay inside KEYSHOT_OUTPUT_DIR unless external outputs are explicitly enabled. |