KeyShot MCP

Turn product-rendering requests into safe, repeatable KeyShot workflows.
将产品渲染需求转化为安全、可重复执行的 KeyShot 工作流。

Inspect scenes, prepare product views, adjust materials, cameras and environments, and return Agent-visible renders through local KeyShot headless scripting.
检查场景、准备产品视图、调整材质、相机和环境，并通过本地 KeyShot headless 脚本将渲染结果返回给 Agent。

Quick start · Highlights · Workflows · Tools · Configuration

English · 简体中文

Useful for your KeyShot workflow? Star the repository to help other designers discover it.
如果它改善了你的 KeyShot 工作流，欢迎点一个 Star，让更多设计师发现这个项目。

KeyShot MCP connects an MCP-compatible AI agent to a licensed KeyShot installation on the same computer. KeyShot file processing stays local; however, an MCP client may send tool results, scene metadata, or embedded previews to its configured model provider. See Security before using confidential work.

English

Highlights

• Start with a request, not a render-settings checklist. Use one product tool for model import, object materials, camera, environment, scene copy, and output.
• See before committing. Bounded PNG previews are returned directly to the Agent for composition, material, and lighting feedback.
• Keep source scenes protected. Editing workflows write controlled copies and reject output paths outside the configured safe directory by default.
• Continue from the latest save. Saved-scene sync detects real file changes, creates a collision-safe copy, and avoids duplicate work with fingerprints.
• Use focused controls when needed. Nineteen documented tools cover inspection, presets, cameras, materials, environments, render queues, and all-camera output.

[!NOTE] Tested on Windows 11 with KeyShot Studio 2025 / KeyShot 14.1. KeyShot and a valid license are required and are not included with this independent project.

Quick start for designers

The easiest setup is to send this prompt to an agent that can edit your MCP configuration:

Install KeyShot MCP 0.12.1 and configure it in my MCP client.

1. Use: npx -y keyshot-mcp@0.12.1
2. Find my local keyshot_headless.exe and set KEYSHOT_HEADLESS_EXE to its full path.
3. Keep outputs in the default KeyShot MCP Outputs folder unless I choose another safe folder.
4. Keep KEYSHOT_ALLOW_EXTERNAL_OUTPUTS disabled.
5. Restart or reload the MCP client and run keyshot_status.
6. Explain any problem and its suggested fix in plain language.
7. Do not upload or publish my KeyShot files, persistent renders, or license information.
8. Before sending a preview image to the configured model provider, remind me when the scene is confidential.

After setup, try:

Check whether KeyShot MCP is ready, then prepare a standard-quality product render
from C:\models\speaker.obj.

Requirements

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

Why the stable release does not control the open KeyShot window

The stable server works on saved scene files through KeyShot headless scripting; it does not control the currently open, unsaved KeyShot GUI session. This is a boundary of the public KeyShot scripting execution model, not an omitted MCP connection. KeyShot's Script Runner keeps a GUI script active until that script returns. In our Live Companion prototype, keeping a bridge alive also kept the Script Runner open and blocked normal interaction with the KeyShot window.

Calling lux.sync() can flush pending KeyShot operations, but it does not provide a documented background service, GUI event callback, or plugin lifecycle that can safely host a persistent MCP bridge. Calling lux from an arbitrary worker thread would also risk unsafe access to the scene. For that reason, the project does not present the experimental bridge as production-ready realtime control.

For a reliable workflow, save the scene first. The Agent can inspect or edit a safe copy through headless KeyShot, return a preview, and preserve the original file. True realtime GUI control can be reconsidered if KeyShot exposes a supported non-blocking GUI extension or main-thread callback API.

Use keyshot_sync_saved_scene for the closest stable alternative to realtime collaboration. Give it a saved .bip file or one folder containing .bip files. It selects the newest saved scene, computes a content fingerprint, copies it to a collision-safe output name, and returns an embedded preview by default. Pass the returned fingerprint on the next call; if the user has not saved a new change, the tool reports changed: false without creating another copy or render.

I saved my KeyShot scene in C:\projects\speaker. Sync the newest .bip from that
folder, show me a preview, and do not overwrite the original scene.

Install

The current release is 0.12.1.

Run with npx

No global npm installation is required:

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

Install globally

npm install -g keyshot-mcp@0.12.1

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

Run from source

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

Point the MCP client to the absolute path of dist/index.js. Ready-to-edit examples are available in examples.

Restart the MCP client after changing its configuration, then call keyshot_status. The status result checks the MCP version, KeyShot executable, output access, bridge files, preset JSON, and a minimal KeyShot startup.

Common workflows

Preview before final rendering

Use keyshot_preview_render after checking a scene. It returns a PNG directly to the Agent, so composition, materials, and lighting can be described and confirmed before a standard or final render. Temporary previews are deleted automatically; set outputPath only when a persistent PNG copy is needed.

Recommended loop: status check -> scene inspection -> preview -> Agent feedback -> user confirmation -> standard or final render.

One-call product render

keyshot_product_render is the recommended high-level tool for ordinary product work. It can import a model or open a scene, apply object-specific materials, configure a camera and environment, save a scene copy, and render in one KeyShot process.

Import C:\models\speaker.obj, center and ground it, use the Isometric camera preset,
set a 55 mm focal length, save a scene copy, and render a standard PNG.

For a new model, import composition options default to enabled. Existing scenes keep their current composition unless explicit changes are requested.

Render every camera

Render every saved camera in C:\scenes\speaker.bip at preview quality. Continue if
one camera fails and do not overwrite existing images.

Use keyshot_batch_render instead when only selected named cameras are required.

Prepare a model without rendering

Import C:\models\speaker.obj, center it, place it on the ground, adjust the camera
target and environment, then save speaker-prepared.bip.

Adjust camera and environment

Set the Product Hero camera to a 55 mm focal length and distance 6, rotate the
current environment to 45 degrees, save a new scene, then render a preview.

fieldOfView and focalLength cannot be used together. position and lookAt are optional, but must be supplied as a pair. samples and maxTimeSeconds select different KeyShot render modes and cannot be combined.

Quality presets