keyshot-mcp

<p align="center">
  <img src="assets/logo-lockup.png" width="620" alt="KeyShot MCP">
</p>

<p align="center">
  <strong>Product rendering in KeyShot, guided by your AI agent.</strong><br>
  <strong>让 AI Agent 协助完成 KeyShot 产品渲染。</strong>
</p>

<p align="center">
  Inspect a saved scene, adjust selected materials and cameras, review a preview, and render a scene copy.<br>
  检查已保存的场景，调整指定对象的材质和相机，先看预览，再从副本出图。
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/keyshot-mcp"><img src="https://img.shields.io/npm/v/keyshot-mcp.svg" alt="npm version"></a>
  <a href="https://github.com/truman-t3/keyshot-mcp/actions/workflows/ci.yml"><img src="https://github.com/truman-t3/keyshot-mcp/actions/workflows/ci.yml/badge.svg" alt="CI status"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License"></a>
  <img src="https://img.shields.io/badge/tools-19-55E6A5" alt="19 MCP tools">
  <img src="https://img.shields.io/badge/KeyShot-14.1_tested-00AEEF" alt="KeyShot 14.1 tested">
  <img src="https://img.shields.io/badge/Node.js-20%2B-339933" alt="Node.js 20 or newer">
  <img src="https://img.shields.io/badge/TypeScript-5.9-3178C6" alt="TypeScript 5.9">
  <img src="https://img.shields.io/badge/MCP-2026--07--28-111827" alt="MCP protocol 2026-07-28">
  <a href="https://m8ven.ai/mcp/truman-t3-keyshot-mcp-v7af97"><img src="https://m8ven.ai/badge/mcp/truman-t3-keyshot-mcp-v7af97?variant=verified" alt="M8ven external verification"></a>
</p>

<p align="center">
  <a href="#english">English</a> · <a href="#中文">简体中文</a><br>
  <a href="#from-a-request-to-a-render--一句话到出图">How it works / 使用流程</a> ·
  <a href="#product-demo--产品实测">Demo / 实测</a> ·
  <a href="#quick-start">Quick start</a> ·
  <a href="#workflows">Workflows</a> ·
  <a href="#tool-reference">Tools</a> ·
  <a href="#快速开始">中文安装</a>
</p>

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

> [!IMPORTANT]
> **Saved scenes, not realtime GUI control.** KeyShot MCP runs headless on the same
> computer as KeyShot. It does not read unsaved edits or control the open KeyShot window.
> **处理已保存的场景，不是实时 GUI 控制。** 服务在本机后台运行 KeyShot，不能读取窗口中尚未保存的修改。
>
> **Client Agent and privacy.** The Agent in your MCP client receives scene information
> and previews returned by tools. Depending on the client's implementation and settings,
> these results may be sent to its configured model provider. KeyShot MCP itself does
> not upload them. Review [privacy and security](SECURITY.md) before confidential work.
>
> **客户端 Agent 与隐私。** MCP 客户端中的 Agent 会接收工具返回的场景信息和预览；
> 这些内容可能根据客户端的实现与配置发送给其所选模型服务。KeyShot MCP 本身不主动上传这些内容。
> 保密项目请先阅读[隐私与安全说明](SECURITY.md)。

## From a Request to a Render / 一句话到出图

After setup, describe the change to your Agent. It uses KeyShot MCP to perform
the work on a saved scene copy; you review the preview before final output.
完成安装后，直接向 Agent 描述需求。它通过 KeyShot MCP 处理已保存场景的副本，
你看过预览、确认效果后，再正式出图。

> **“Change the lantern's metal to brushed steel, keep the glass unchanged, and show me a preview. Once I approve, export the image and a scene copy.”**
>
> **“把灯具的金属换成拉丝钢，玻璃保持不变，先给我看预览。确认后输出图片和场景副本。”**

<picture>
  <source media="(max-width: 600px)" srcset="assets/workflow-mobile.svg">
  <img src="assets/workflow.svg" alt="需求 → Agent 确认对象和材质 → KeyShot 修改副本 → 查看预览 → 确认后输出 PNG 与 .bip；Request → Check → Edit copy → Preview → Export" width="1160">
</picture>

Not happy with the preview? Ask for another adjustment before exporting.
预览不满意，可以继续说“再调整一下”；原始场景不覆盖，最终文件写入配置的输出目录。

## Product Demo / 产品实测

<p align="center">
  <img src="assets/demo/lantern/brass.png" alt="Brass / 黄铜外观：修正透明玻璃的灯具" width="420">
  <img src="assets/demo/lantern/steel.png" alt="Brushed steel / 拉丝钢外观：仅替换金属对象，保持玻璃不变" width="420">
</p>

<p align="center"><strong>Brass / 黄铜外观 · Brushed steel / 拉丝钢外观</strong></p>

**One selected object, two finishes.** Both images were rendered in KeyShot 14.1
at 1440 × 1080, 64 samples, with the same camera and environment. The glass was
explicitly corrected before the comparison; only the metal changed between images.

**同一个对象，两种材质方案。** 两张图采用相同相机、环境及 1440 × 1080、64 samples
参数，由 KeyShot 14.1 实测生成。先修正导入的玻璃，再仅替换金属对象，玻璃保持不变。

Model: [Lantern 01](https://polyhaven.com/a/Lantern_01) by **Rajil Jose Macatangay**,
from **Poly Haven**, licensed under [CC0](https://polyhaven.com/license).
These are local KeyShot renders, not Poly Haven website previews.
模型来源、作者与 CC0 许可如上；展示图为本地渲染，不是网站官方预览图。

[Reproduce the workflow / 复现演示](examples/lantern-demo/README.md) ·
[Asset credits / 素材说明](assets/demo/lantern/ATTRIBUTION.md)

## English

### What You Can Do

- **Prepare a product shot:** import a model or open a scene, configure selected
  materials, camera and environment, save a copy and render in one KeyShot process.
- **Review before final output:** return a PNG to the Agent for composition,
  material and lighting feedback. Design decisions stay with the user.
- **Continue from a save:** detect saved `.bip` changes, copy the scene and preview
  it without reading the active GUI session.
- **Render multiple views:** discover all saved cameras, select particular cameras,
  or queue different scenes for sequential rendering.

### Quick Start

**Requirements:** Node.js 20+, an MCP-compatible client, and a locally installed,
licensed KeyShot edition with headless scripting. **Windows 11 + KeyShot Studio
2025 / KeyShot 14.1 is tested.** Other systems and KeyShot versions are not verified.
KeyShot software, licenses and library assets are not included.

<!-- release-version: 0.13.1 -->

**Version 0.13.1** includes verified material assignments, clearer material-file
errors and the updated designer workflow documentation. Installation examples
below target this version. See the [release validation record and 1.0 checklist](docs/RELEASE-READINESS.md).
See [Changelog](CHANGELOG.md) and [upgrade notes](docs/UPGRADING.md).

#### Ask Your Agent to Install

Send this to an Agent that can edit your client's MCP configuration:

```text
Install KeyShot MCP 0.13.1 in my MCP client using npx -y keyshot-mcp@0.13.1.
Find the full path of my local keyshot_headless.exe and set KEYSHOT_HEADLESS_EXE.
Keep the default Documents/KeyShot MCP Outputs folder and external outputs disabled.
Use my client's configuration format, restart or reload it, and run keyshot_status.
Explain failed checks in plain language. Do not request or upload license keys.
Do not upload or publish my scenes or retained render files.
Before showing confidential scene metadata or previews to a model service, ask me first.
```

#### Configure It Yourself

This is a generic `mcpServers` JSON example. Use your client's configuration format
and replace the executable path with the actual path on your computer.

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

Restart the client, run `keyshot_status`, and check for `ready: true`. It verifies
the executable, output access, bridge, presets and a minimal KeyShot startup.

<details>
<summary>Global npm installation or source build</summary>

**Global:** run `npm install -g keyshot-mcp@0.13.1`, then use `keyshot-mcp` as the
client command with no `npx` arguments. Keep the same environment settings.

**Source:**

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

Use `node` as the command and the absolute path to `dist/index.js` as its argument.
The checked-out source can be newer than npm. Client examples are in [`examples`](examples).

</details>

### Workflows

#### Preview Before Rendering

```text
Inspect C:\projects\speaker.bip and show a preview. Describe framing or material
problems, but wait for approval before editing or producing a final render.
```

Recommended sequence: **check status → inspect → preview → discuss → approve → render**.
`keyshot_preview_render` embeds a PNG and deletes its temporary file after reading.
Provide `outputPath` only when a saved image is needed.

#### Make a Product Render

```text
Import C:\models\speaker.obj, center it and place it on the ground. Use Isometric,
save a scene copy and show a preview first. If the framing clips the model, propose
a camera adjustment before rendering the approved scene at standard quality.
```

`keyshot_product_render` accepts one model or one saved scene. New models use import
composition options by default; existing scenes keep their setup unless changes
are requested. Automatic framing is a starting point, not a guarantee.

#### Compare Materials on One Object

```text
Inspect the saved scene and list material presets. Identify the metal object,
change only that object to Brushed Steel in a scene copy, keep the glass unchanged,
and show a preview before final rendering.
```

Use the returned `objectPath` when names repeat. Material names depend on the local
KeyShot library; do not invent them. See [material rules](docs/MATERIALS.md).

#### Continue After Saving in KeyShot

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

`keyshot_sync_saved_scene` accepts a file or one project folder. Reuse the previous
fingerprint on later calls; unchanged saves return `changed: false` without another
copy or render. It is explicit sync, not automatic background monitoring.

#### Render All Cameras

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

For selected cameras use `keyshot_batch_render`; for different scenes use `keyshot_render_queue`.

#### Prepare a Model Without Rendering

```text
Import C:\models\spe