KeyShot MCP

Product rendering in KeyShot, guided by your AI agent.

让 AI Agent 协助完成 KeyShot 产品渲染。

Inspect a saved scene, adjust selected materials and cameras, review a preview, and render a scene copy.

检查已保存的场景，调整指定对象的材质和相机，先看预览，再从副本出图。

English · 简体中文

How it works / 使用流程 · Demo / 实测 · Quick start · Workflows · Tools · 中文安装

Useful for your KeyShot workflow? Star the repository to help other designers discover it.

如果它改善了你的 KeyShot 工作流，欢迎点一个 Star，让更多设计师发现这个项目。

[!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 before confidential work.

客户端 Agent 与隐私。 MCP 客户端中的 Agent 会接收工具返回的场景信息和预览；

这些内容可能根据客户端的实现与配置发送给其所选模型服务。KeyShot MCP 本身不主动上传这些内容。

保密项目请先阅读隐私与安全说明。

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.”

“把灯具的金属换成拉丝钢，玻璃保持不变，先给我看预览。确认后输出图片和场景副本。”

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

Product Demo / 产品实测

Brass / 黄铜外观 · Brushed steel / 拉丝钢外观

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 by Rajil Jose Macatangay, from Poly Haven, licensed under CC0. These are local KeyShot renders, not Poly Haven website previews. 模型来源、作者与 CC0 许可如上；展示图为本地渲染，不是网站官方预览图。

Reproduce the workflow / 复现演示 · Asset credits / 素材说明

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.

Version 1.0.0. This release preserves 19 tools and adds corrected product framing and dependency patches. Client and independent-user acceptance are deferred, not passed. See the release validation record and 1.0 checklist. See Changelog and upgrade notes.

Ask Your Agent to Install

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

Install KeyShot MCP 1.0.0 in my MCP client using npx -y keyshot-mcp@1.0.0.

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.

{

"mcpServers": { "keyshot": { "command": "npx", "args": ["-y", "keyshot-mcp@1.0.0"], "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.

Global npm installation or source build

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

Source:

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.

Workflows

Preview Before Rendering

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

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. In 1.0.0, standard-view cameras for new models without a base scene fit the world-space scene bounds to the render aspect ratio, with 10% edge padding. Explicit distance, absolute camera coordinates and base scenes keep their framing. This includes all scene geometry, not just the main product; review a preview before final rendering.

Compare Materials on One Object

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.

Continue After Saving in KeyShot

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

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

Import C:\models\speaker.obj, center it, place it on the ground and adjust the

camera target and environment. Save a scene copy; do not render an image yet.

Use keyshot_import_model when only a prepared .bip is needed.

Adjust the Lens and Environment

Set the Product Hero camera to a 55 mm focal length, rotate the current

environment to 45 degrees, save a scene copy and show a preview.

Use keyshot_set_camera and keyshot_set_environment for focused changes.

Render Quality

Explicit dimensions and samples override presets. maxTimeSeconds switches to time-based rendering and cannot be combined with explicit samples. fieldOfView and focalLength are mutually exclusive; camera position and lookAt must be supplied together. A quality preset does not guarantee the final look. Lower-level rendering tool