Control local KeyShot scenes, cameras, environments, and renders through headless scripting.
io.github.truman-t3/keyshot-mcp MCP Server
Control local KeyShot scenes, cameras, environments, and renders through headless scripting. It inspects scenes, prepares product views, adjusts materials, cameras, and environments, and returns Agent-visible renders by running KeyShot headlessly on the local machine.
🛠️ Key Features
Control KeyShot scenes via headless scripting
Inspect scenes and prepare product views
Adjust materials, cameras, and environments
Return Agent-visible renders from local KeyShot
🚀 Use Cases
Product-rendering and product-visualization workflows
Industrial-design rendering pipelines requiring repeatable scene setup
Camera and environment configuration for product views
⚡ Developer Benefits
Integrates with the Model Context Protocol (MCP)
Supports workflows implemented with TypeScript tooling
Uses local headless rendering to produce renders for an Agent
⚠️ Limitations
Intended to operate through local KeyShot headless scripting (no remote/cloud rendering details provided)
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.
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.
Model: Lantern 01 by Rajil Jose Macatangay,
from Poly Haven, licensed under CC0.
These are local KeyShot renders, not Poly Haven website previews.
模型来源、作者与 CC0 许可如上;展示图为本地渲染,不是网站官方预览图。
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.
Send this to an Agent that can edit your client's MCP configuration:
text
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.
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:
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.
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. 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
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.
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\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
text
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
Preset
Resolution
Samples
Typical Use
preview
960 × 540
16
Composition and material checks
standard
1920 × 1080
64
Default product-render quality
final
3840 × 2160
256
High-resolution output
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 tools keep their existing defaults when qualityPreset is omitted.
Tool Reference
Start with review and product rendering. The other tools provide focused control;
full parameters come from the generated catalog.
The server also provides a product-render MCP Prompt and a workflow MCP Resource.
The bundled Agent Skill covers setup, diagnosis and
safe tool selection. These are separate interfaces, not extra render tools.
Camera and Material Presets
The bundled camera presets are Front, Back, Left, Right, Top, Bottom and Isometric.
Custom camera JSON supports a standardView or absolute position, lookAt and
optional up. Both object and array formats are supported; see the preset files.
Material presets reference a local KeyShot library name or material file, not bundled
proprietary materials. The server only reads preset JSON; it does not edit it.
Use KEYSHOT_CAMERA_PRESETS and KEYSHOT_MATERIAL_PRESETS for custom files.
See material assignment and error guidance.
Configuration and Safety
Variable
Default
Purpose
KEYSHOT_HEADLESS_EXE
Windows: keyshot_headless.exe
Full executable path or command on PATH
KEYSHOT_OUTPUT_DIR
<home>/Documents/KeyShot MCP Outputs
Allowed output root
KEYSHOT_ALLOW_EXTERNAL_OUTPUTS
false
Explicitly allow trusted external output paths
KEYSHOT_TIMEOUT_MS
600000
Timeout per process, in milliseconds
KEYSHOT_CAMERA_PRESETS
bundled JSON
Custom camera presets
KEYSHOT_MATERIAL_PRESETS
bundled JSON
Custom material references
KEYSHOT_LICENSE_ARGS
empty
Optional launch arguments; diagnostics never echo values
Inputs can come from any trusted local path. Output traversal and symlink/junction
escapes are rejected by default. Automatically named product outputs use -2,
-3, etc. on collision; explicit paths are not silently renamed. Writing tools reject
existing files by default. Set overwrite: true only to replace a distinct output
intentionally; it never permits replacing this request's input scene, model, material
or environment, including linked aliases. Preview and saved-scene sync never overwrite.
Keep scene and image destinations separate. Prefer scene copies.
KeyShot headless tasks run sequentially within each server instance to reduce
license and file conflicts; this does not coordinate separate MCP server processes.
Processing is local. When an Agent in your MCP client uses these tools, the client
may send tool results, scene metadata and preview images to its selected model provider,
depending on the client's implementation and settings. KeyShot MCP itself does not
upload these results. Review privacy settings before confidential work. No license
bypass or arbitrary Python execution is provided. See Security.
Questions and Support
Can it edit the open KeyShot window? No. Save the scene, then sync a copy.
The experimental bridge kept Script Runner active and blocked interaction;
the stable product does not ship it. Technical explanation.
Does newer MCP support mean ChatGPT Events or GUI support? No. The stable stdio
server supports 2026-07-28 and legacy 2025-11-25 clients. Authenticated remote
Events delivery is separate and not released. See upgrade notes.
What if setup, materials or rendering fail? Run keyshot_status, read its failed
checks and suggestions, verify local material names and try a small preview.
Do not treat a tool error as a completed change.
Read Support before sharing logs. Never post private scenes, customer
models, credentials, license information or confidential renders publicly.
Development and Roadmap
See Contributing for setup and checks. CI covers Windows/Ubuntu
and Node.js 20/24; Linux CI does not establish KeyShot-on-Linux support.
The generated cube remains an automated smoke-test fixture. Run npm run smoke:keyshot
only with a supported, licensed local KeyShot installation.
Next priorities: real validation on more KeyShot releases and macOS, and further lens
controls when stable headless APIs are available. GUI control requires a supported
non-blocking integration, not a persistent blocking script.
License and Independence
Code is MIT-licensed. Third-party demo assets retain their own licenses.
KeyShot is a trademark of KeyShot ApS and/or KeyShot Inc. This independent community
project is not affiliated with, endorsed by or sponsored by KeyShot. Install and
license KeyShot separately; do not redistribute its proprietary software or assets.
Community conduct is covered by Code of Conduct.
中文
核心特点
把需求变成出图流程: 一个工具串联导入或打开场景、指定对象材质、相机、环境、保存副本和渲染。
先看预览再决定: PNG 直接返回给 Agent,用于讨论构图、材质与光线,不替代设计判断。
接着已保存的文件工作: 检测 .bip 保存变化,同步副本,不读取 GUI 中未保存的编辑。
一次输出多个视角: 自动读取全部相机,也能选择部分相机或顺序处理多个场景。
快速开始
需要 Node.js 20+、支持 MCP 的客户端,以及本机已安装并合法授权、支持 headless 脚本的
KeyShot。已实测 Windows 11 + KeyShot Studio 2025 / KeyShot 14.1;其他系统和
KeyShot 版本尚未实机验证。项目不包含 KeyShot、许可证或官方材质库。