keyshot-mcp

# KeyShot MCP

[![npm version](https://img.shields.io/npm/v/keyshot-mcp.svg)](https://www.npmjs.com/package/keyshot-mcp)
[![CI](https://github.com/truman-t3/keyshot-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/truman-t3/keyshot-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

[English](#english) | [中文](#中文)

KeyShot MCP is a local [Model Context Protocol](https://modelcontextprotocol.io/)
server for inspecting, editing, and rendering KeyShot scenes through KeyShot
headless scripting. It lets an MCP-compatible AI agent perform repeatable product
visualization tasks while scenes, models, licenses, and rendered files remain on
the local computer.

![KeyShot MCP workflow](assets/workflow.svg)

## English

### What it can do

- Inspect scene objects, materials, cameras, model sets, and external references.
- Import models and optionally center them, place them on the ground, update the
  camera target, and adjust the environment.
- Render one camera, selected cameras, every camera in a scene, or a sequential
  render queue.
- Create and update cameras by position, look-at point, distance, field of view,
  focal length, or reusable presets.
- Apply materials directly or through a local material preset library.
- Select environments, change brightness, and rotate the active environment.
- Save edited scenes to a controlled output directory.
- Prepare and render a product from a model or existing scene in one tool call.

### Requirements and compatibility

- Node.js 20 or newer.
- A locally installed and licensed KeyShot version with headless scripting.
- Windows 11 with KeyShot Studio 2025 / KeyShot 14.1 is tested.
- Other KeyShot versions may work when they expose the same official scripting
  APIs, but they are not currently verified by this project.
- KeyShot and its license are not included.

### Install

The current release is `0.9.0`.

#### Option 1: run with npx

This requires no global npm installation:

```json
{
  "mcpServers": {
    "keyshot": {
      "command": "npx",
      "args": ["-y", "keyshot-mcp@0.9.0"],
      "env": {
        "KEYSHOT_HEADLESS_EXE": "C:/Program Files/KeyShot Studio/bin/keyshot_headless.exe"
      }
    }
  }
}
```

#### Option 2: install globally

```bash
npm install -g keyshot-mcp@0.9.0
```

```json
{
  "mcpServers": {
    "keyshot": {
      "command": "keyshot-mcp",
      "env": {
        "KEYSHOT_HEADLESS_EXE": "C:/Program Files/KeyShot Studio/bin/keyshot_headless.exe"
      }
    }
  }
}
```

#### Option 3: run from source

```bash
git clone https://github.com/truman-t3/keyshot-mcp.git
cd keyshot-mcp
pnpm install
pnpm build
```

Configure the MCP client to run the absolute path to `dist/index.js`:

```json
{
  "mcpServers": {
    "keyshot": {
      "command": "node",
      "args": ["C:/absolute/path/to/keyshot-mcp/dist/index.js"],
      "env": {
        "KEYSHOT_HEADLESS_EXE": "C:/Program Files/KeyShot Studio/bin/keyshot_headless.exe"
      }
    }
  }
}
```

Restart the MCP client after changing its configuration.

### Agent installation prompt

The following prompt can be pasted into a coding agent that is allowed to edit
the MCP client configuration:

```text
Install KeyShot MCP 0.9.0 and configure it in my MCP client.

1. Find the local KeyShot headless executable.
2. Add an MCP server named "keyshot" that runs:
   npx -y keyshot-mcp@0.9.0
3. Set KEYSHOT_HEADLESS_EXE to the executable path.
4. Keep KEYSHOT_ALLOW_EXTERNAL_OUTPUTS disabled.
5. Restart or reload the MCP client, call keyshot_status, then use keyshot_product_render for a one-click product render.
6. Do not upload or publish any KeyShot scenes, models, renders, or license data.
```

### Configuration

| Variable | Default | Purpose |
| --- | --- | --- |
| `KEYSHOT_HEADLESS_EXE` | `keyshot_headless.exe` on Windows | Absolute executable path or a command available on `PATH`. |
| `KEYSHOT_OUTPUT_DIR` | `~/Documents/KeyShot MCP Outputs` | Root directory for rendered images and saved scenes. |
| `KEYSHOT_ALLOW_EXTERNAL_OUTPUTS` | `false` | Allows output paths outside `KEYSHOT_OUTPUT_DIR` when explicitly set to `true`. |
| `KEYSHOT_TIMEOUT_MS` | `600000` | Timeout for one KeyShot headless process. |
| `KEYSHOT_LICENSE_ARGS` | empty | Optional additional KeyShot launch arguments. |
| `KEYSHOT_MATERIAL_PRESETS` | Built-in `presets/materials.json` | Path to a user-managed material preset file. |
| `KEYSHOT_CAMERA_PRESETS` | Built-in `presets/cameras.json` | Path to a user-managed camera preset file. |

Relative output paths are resolved inside `KEYSHOT_OUTPUT_DIR`. Parent traversal,
adjacent-prefix paths, and symbolic-link escapes are rejected by default. Input
scene, model, material, and environment paths may be located elsewhere.

Run `keyshot_status` after installation. It reports the MCP and KeyShot
versions, resolved executable, output write access, preset validity, headless
startup result, and actionable suggestions. Additional KeyShot launch arguments
are never included in the diagnostic output.

### Tools

| Tool | Purpose |
| --- | --- |
| `keyshot_status` | Diagnose local configuration, output access, presets, and KeyShot headless startup. |
| `keyshot_product_render` | Prepare, save, and render a model or existing scene in one headless process. |
| `keyshot_inspect_scene` | Inspect objects, cameras, materials, model sets, and references. |
| `keyshot_list_cameras` | List available camera names. |
| `keyshot_render` | Render one image. |
| `keyshot_render_queue` | Run independent render jobs sequentially. |
| `keyshot_batch_render` | Render a supplied list of named cameras from one scene. |
| `keyshot_render_all_cameras` | Discover and render every camera in one scene. |
| `keyshot_import_model` | Import a model with optional composition adjustments. |
| `keyshot_apply_material` | Apply a library material or material file. |
| `keyshot_list_material_presets` | List local material presets. |
| `keyshot_apply_material_preset` | Apply a named material preset. |
| `keyshot_set_camera` | Create or update camera transform, distance, FOV, or focal length. |
| `keyshot_list_camera_presets` | List standard and custom camera presets. |
| `keyshot_apply_camera_preset` | Apply a standard or absolute-coordinate camera preset. |
| `keyshot_set_environment` | Select or adjust an environment, brightness, or rotation. |
| `keyshot_save_scene` | Save a scene to a new output path. |

The server exposes 17 tools, a `keyshot_product_render` MCP prompt, and a
`keyshot://workflow` resource.

### One-click product render

In an MCP client, a designer can use a natural-language request:

```text
Turn C:\models\speaker.obj into a product render. Center it, place it on the
ground, use the Isometric camera preset, save the KeyShot scene, and render a
1600 x 1200 PNG with 128 samples.
```

The `keyshot_product_render` tool accepts either `modelPath` or `scenePath`. New
models default to centered and grounded geometry with a `Product Hero`
isometric camera. Existing scenes keep their current camera, materials, and
environment unless explicit changes are requested.

One-click product rendering defaults to the `standard` quality preset. All
rendering tools accept:

| Preset | Resolution | Samples |
| --- | ---: | ---: |
| `preview` | 960 × 540 | 16 |
| `standard` | 1920 × 1080 | 64 |
| `final` | 3840 × 2160 | 256 |

Explicit `width`, `height`, or `samples` values override the corresponding
preset value. `maxTimeSeconds` replaces preset samples. Explicit `samples` and
`maxTimeSeconds` cannot be used together.

```json
{
  "modelPath": "C:/models/speaker.obj",
  "outputScenePath": "speaker-product.bip",
  "outputPath": "speaker-product.png",
  "materialAssignments": [
    { "objectName": "Body", "presetName": "Brushed Steel" }
  ],
  "cameraPresetName": "Isometric",
  "focalLength": 55,
  "brightness": 1.2,
  "rotation": 45,
  "qualityPreset": "standard"
}
```

Use `renderMode: "allCameras"` with `outputDir` to render every named camera.
Generated names are derived from the source filename when output paths are
omitted. If an automatically named result exists, the scene and image receive
the same `-2`, `-3`, and later suffix. Explicit output paths remain protected
and return an error when occupied; set `overwrite: true` only when replacement
is intentional. Material assignments always require an
explicit object and never overwrite the entire model implicitly.

### Product composition examples

Import a model and prepare its initial composition:

```text
Import C:\models\speaker.obj into KeyShot. Center the geometry, place it on the
ground, update the camera look-at point and environment, then save the scene as
speaker-prepared.bip.
```

The corresponding `keyshot_import_model` options are:

```json
{
  "centerGeometry": true,
  "snapToGround": true,
  "adjustCameraLookAt": true,
  "adjustEnvironment": true
}
```

Create a product camera with one lens control:

```text
Set the Product Hero camera to a 55 mm focal length and distance 6, save a new
scene, then render a PNG preview.
```

`fieldOfView` must be greater than `0` and less than `180`. `focalLength` accepts
`5` to `200` mm. The two controls are mutually exclusive. `position` and
`lookAt` are optional, but must be supplied together when changing the transform.

Rotate the active HDRI or environment:

```text
Rotate the current KeyShot environment to 45 degrees, save the edited scene,
and render all cameras.
```

`rotation` accepts values from `0` inclusive to `360` exclusive.

For rendering, `samples` and `maxTimeSeconds` select different KeyShot render
modes and cannot be supplied together.

### Camera and material presets

The built-in camera library includes Front, Back, Left, Right, Top, Bottom, and
Isometric views. A custom `KEYSHOT_CAMERA_PRESETS` JSON file may contain standard
views or absolute `position`, `lookAt`, and optional `up` vectors.

Material presets are stored in JSON and reference KeyShot library