KeyShot MCP

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. It can inspect scenes, import models, apply materials, set cameras and environments, save scene copies, and render images through KeyShot headless scripting. Models, scenes, licenses, and renders stay local.

English

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.9.1 and configure it in my MCP client.

1. Use: npx -y keyshot-mcp@0.9.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, renders, or license information.

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.

Install

The current release is 0.9.1.

Run with npx

No global npm installation is required:

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

Install globally

npm install -g keyshot-mcp@0.9.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

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

Explicit width, height, and samples override the corresponding preset values. Explicit maxTimeSeconds switches to time-based rendering instead of preset samples. Lower-level render tools preserve their existing behavior when no preset is given.

Tools

The server also exposes one MCP Prompt for product rendering and one MCP Resource describing the KeyShot headless workflow. The bundled Agent Skill in skills/keyshot-mcp teaches compatible agents how to install, diagnose, and use the server safely.

Configuration

All KeyShot operations run sequentially to reduce license and output conflicts. Input scenes and models may come from any local path. By default, generated images and scenes must remain inside KEYSHOT_OUTPUT_DIR; .., sibling-prefix, and symlink/junction escapes are rejected.

Automatically generated product outputs use -2, -3, and later suffixes when a name already exists. Explicit output paths are not silently renamed. Operations that support overwrite require it to be set deliberately before replacing files.

Camera and material presets

The bundled camera library contains Front, Back, Left, Right, Top, Bottom, and Isometric standard views. A custom camera JSON may define a standard view or an absolute position, lookAt, and optional up vector.

Material presets reference a KeyShot library material name or local material file. The MCP server reads preset files but does not edit them automatically. See presets for the supported formats.

Reproducible KeyShot demo

The repository includes a smoke test built from generated cube geometry in examples/demo. It verifies startup, import composition, scene inspection, camera presets, lens controls, environment rotation, scene saving, camera discovery, one-call product rendering, and real PNG output.

npm run smoke:keyshot

Generated .bip files and test renders stay in the configured local output directory. A representative result is included below:

Development

pnpm install
pnpm check
pnpm test
python -m unittest discover -s tests -p "test_*.py"
npm pack --dry-run

CI runs on Windows and Ubuntu with Node.js 20 and 24. Linux CI validates the MCP server, bridge logic, metadata, and package; it does not claim that KeyShot itself was tested on Linux.

Roadmap

• Verify additional supported KeyShot releases on real installations.
• Verify macOS installation and headless behavior.
• Add depth-of-field and additional lens controls when stable headless APIs exist.

License, security, and trademarks

This project uses the MIT License. See SECURITY.md for security reporting and CONTRIBUTING.md for development guidance. Do not commit licenses, private scenes, customer assets, or unpublished renders.

KeyShot is a trademark of KeyShot ApS and/or KeyShot Inc. This independent open-source community project is not affiliated with, endorsed by, sponsored by, or otherwise associated with KeyShot. Users must install and license KeyShot separately and comply with its applicable terms. This project must not be used to bypass licensing or redistribute proprietary KeyShot software or assets.

中文

设计师快速开始

最简单的安装方式，是把下面这段话发给能够修改 MCP 配置的 Agent：

请安装 KeyShot MCP 0.9.1，并配置到我的 MCP 客户端。

1. 使用：npx -y keyshot-mcp@0.9.1
2. 查找本机 keyshot_headless.exe，并把完整路径设置为 KEYSHOT_HEADLESS_EXE。
3. 默认把结果保存在“文档/KeyShot MCP Outputs”，除非我明确选择其他安全目录。
4. 保持 KEYSHOT_ALLOW_EXTERNAL_OUTPUTS 关闭。
5. 重启或重新加载 MCP 客户端，然后运行 keyshot_status。
6. 用普通设计师能理解的语言说明问题和修复建议。
7. 不要上传或发布我的 KeyShot 文件、渲染图或许可证信息。

安装后可以这样说：

检查 KeyShot MCP 是否准备就绪，然后用 C:\models\speaker.obj 生成一张标准质量的产品渲染图。

使用要求

• Node.js 20 或更高版本。
• 本机已安装、合法授权并支持 headless 脚本的 KeyShot。
• 已实测 Windows 11 + KeyShot Studio 2025 / KeyShot 14.1。
• 暴露相同脚本 API 的其他 KeyShot 版本可能可用，但本项目暂未完成实机验证。
• 本项目不包含 KeyShot、许可证、官方材质或环境资源。

安装

当前正式版本为 0.9.1。

使用 npx 免安装运行

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

全局安装

npm install -g keyshot-mcp@0.9.1

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

从源码运行

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

在 MCP 客户端中填写 dist/index.js 的绝对路径。可编辑配置示例位于 examples。修改配置后重启 MCP 客户端，再调用 keyshot_status。

状态检查会验证 MCP 版本、KeyShot 可执行文件、输出目录、bridge、预设 JSON， 并运行最小 KeyShot 启动测试。

常用工作流

一句话完成产品出图

普通产品工作优先使用 keyshot_product_render。它能在一个 KeyShot 进程中导入模型 或打开场景、应用指定材质、调整相机和环境、保存场景副本并渲染图片。

导入 C:\models\speaker.obj，自动居中贴地，使用 Isometric 相机预设和 55 mm 焦距，
保存场景副本并输出标准质量 PNG。

新模型的导入构图选项默认开启；已有场景在没有明确要求时保留现有构图。

渲染全部相机

用预览质量渲染 C:\scenes\speaker.bip 中的全部相机。某个相机失败时继续，
并且不要覆盖已有图片。

只渲染部分指定相机时，使用 keyshot_batch_render。

只整理模型，不渲染

导入 C:\models\speaker.obj，自动居中、贴地、调整相机观察点和环境，
然后保存为 speaker-prepared.bip。

调整相机和环境

把 Product Hero 相机设置为 55 mm 焦距、距离 6，把当前环境旋转到 45 度，
保存新场景并渲染预览图。

fieldOfView 与 focalLength 不能同时使用。position 和 lookAt 可以省略， 但修改位置时必须成对提供。samples 与 maxTimeSeconds 对应不同渲染模式， 不能同时使用。

质量预设

显式填写的 width、height 和 samples 会分别覆盖预设值；填写 maxTimeSeconds 会改用限时渲染。底层渲染工具在没有指定预设时保持原有行为。

工具

服务还提供一个产品渲染 MCP Prompt，以及一个说明 headless 工作流程的 MCP Resource。 skills/keyshot-mcp 中的 Agent Skill 会指导兼容的 Agent 安装、 诊断并安全使用这些工具。

配置

所有 KeyShot 操作串行执行，减少许可证和文件冲突。输入模型和场景可以位于任意本地 路径；生成的场景和图片默认只能写入 KEYSHOT_OUTPUT_DIR。系统会拒绝 ..、同名前缀 目录以及符号链接或目录联接逃逸。

自动生成的产品输出遇到重名时会使用 -2、-3 等编号。用户明确填写的路径不会 被静默改名；支持 overwrite 的操作只有在明确开启后才覆盖文件。

相机与材质预设

内置相机库包含 Front、Back、Left、Right、Top、Bottom 和 Isometric 七个标准视角。 自定义相机 JSON 可使用标准视角，也可提供绝对 position、lookAt 和可选 up。

材质预设引用 KeyShot 材质库名称或本地材质文件。MCP 只读取预设文件，不自动修改。 格式示例见 presets。

可复现的 KeyShot Demo

仓库使用 examples/demo 中生成的立方体几何体进行 smoke test， 验证启动、导入构图、场景检查、相机预设、镜头控制、环境旋转、场景保存、相机发现、 一键产品出图和真实 PNG 输出。

npm run smoke:keyshot

生成的 .bip 和测试渲染图只保存在本地输出目录。仓库提供一张代表性结果：

开发与测试

pnpm install
pnpm check
pnpm test
python -m unittest discover -s tests -p "test_*.py"
npm pack --dry-run

CI 在 Windows 和 Ubuntu 上使用 Node.js 20、24。Linux CI 验证 MCP 服务、bridge、 元数据和 npm 包，不表示 KeyShot 软件已经在 Linux 上通过实机测试。

路线图

• 在更多受支持的 KeyShot 正式版本上完成实机验证。
• 验证 macOS 安装和 headless 行为。
• 在稳定 headless API 可用后增加景深和更多镜头控制。

许可证、安全与商标

项目采用 MIT License。安全报告方式见 SECURITY.md， 开发说明见 CONTRIBUTING.md。请勿提交许可证、私有场景、客户素材 或未公开渲染图。

KeyShot 是 KeyShot ApS 和/或 KeyShot Inc. 的商标。本项目是独立开源社区项目， 与 KeyShot 官方无隶属、认可、赞助或其他合作关系。用户必须自行安装并合法授权 KeyShot，同时遵守适用条款。不得使用本项目绕过许可证或重新分发 KeyShot 专有软件 及资源。