KeyShot MCP

在 AI Agent 的指导下，使用 KeyShot 进行产品渲染。
让 AI Agent 协助完成 KeyShot 产品渲染。

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

English · 简体中文
工作原理 / 使用流程 · 演示 / 实测 · 快速开始 · 工作流 · 工具 · 中文安装

KeyShot 工作流对你有帮助吗？欢迎给仓库点一个 Star，让更多设计师发现它。
如果它改善了你的 KeyShot 工作流，欢迎点一个 Star，让更多设计师发现这个项目。

重要

处理已保存的场景，而非实时控制 GUI。 KeyShot MCP 与 KeyShot 在同一台 计算机上以无头模式运行。它不会读取未保存的修改，也不会控制已打开的 KeyShot 窗口。 处理已保存的场景，不是实时 GUI 控制。 服务在本机后台运行 KeyShot，不能读取窗口中尚未保存的修改。

客户端 Agent 与隐私。 MCP 客户端中的 Agent 会接收工具返回的场景信息 和预览。根据客户端的实现和设置，这些结果可能会发送给其配置的模型服务提供商。 KeyShot MCP 本身不会上传这些内容。处理机密项目之前，请阅读隐私与安全说明。

客户端 Agent 与隐私。 MCP 客户端中的 Agent 会接收工具返回的场景信息和预览； 这些内容可能根据客户端的实现与配置发送给其所选模型服务。KeyShot MCP 本身不主动上传这些内容。 保密项目请先阅读隐私与安全说明。

从需求到出图 / 一句话到出图

完成安装后，向你的 Agent 描述要做的更改。它会通过 KeyShot MCP 在已保存场景的副本上完成操作；你可以在最终输出前检查预览。 完成安装后，直接向 Agent 描述需求。它通过 KeyShot MCP 处理已保存场景的副本， 你看过预览、确认效果后，再正式出图。

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

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

如果对预览不满意，可以在导出前要求再次调整。 预览不满意，可以继续说“再调整一下”；原始场景不覆盖，最终文件写入配置的输出目录。

产品演示 / 产品实测

黄铜外观 · 拉丝钢外观

同一个对象，两种材质方案。 两张图均使用相同的相机和环境，在 KeyShot 14.1 中以 1440 × 1080、64 次采样渲染。对比前已明确修正玻璃；两张图之间仅金属有所变化。

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

模型：Lantern 01，作者为 Rajil Jose Macatangay， 来自 Poly Haven，采用 CC0 许可。 这些是 KeyShot 本地渲染图，并非 Poly Haven 网站预览图。 模型来源、作者与 CC0 许可如上；展示图为本地渲染，不是网站官方预览图。

复现工作流 / 复现演示 · 素材致谢 / 素材说明

英文

可以做什么

• 制作产品图： 导入模型或打开场景，配置所选材质、相机和环境，在一个 KeyShot 进程中保存副本并渲染。
• 最终输出前先审阅： 将 PNG 返回给 Agent，以便获取构图、材质和灯光方面的反馈。设计决策由用户做出。
• 从已保存场景继续： 检测已保存的 .bip 更改，复制场景并生成预览，而不读取当前 GUI 会话。
• 渲染多个视图： 发现所有已保存的相机、选择特定相机，或将不同场景加入队列依次渲染。

快速开始

要求： Node.js 20+、兼容 MCP 的客户端，以及本地安装并获得许可、支持无头脚本的 KeyShot 版本。已测试 Windows 11 + KeyShot Studio 2025 / KeyShot 14.1。 其他系统和 KeyShot 版本未经验证。 不包含 KeyShot 软件、许可证和资源库素材。

版本 0.13.5。 此维护版本强化了输出保护、预览范围限制、发布隐私保护、Windows 安装路径和启动诊断。以下安装示例适用于此版本。请参阅发布验证记录和 1.0 检查清单。 另请参阅更新日志和升级说明。

让你的 Agent 安装

将以下内容发送给能够编辑客户端 MCP 配置的 Agent：

Install KeyShot MCP 0.13.5 in my MCP client using npx -y [email protected].
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.

自行配置

这是一个通用的 mcpServers JSON 示例。请使用客户端的配置格式，并将可执行文件路径 替换为你计算机上的实际路径。

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

重启客户端，运行 keyshot_status，并检查是否显示 ready: true。此操作会验证 可执行文件、输出访问权限、桥接程序、预设以及 KeyShot 的基本启动情况。

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

工作流

渲染前先预览

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.

推荐顺序：检查状态 → 查看 → 预览 → 讨论 → 批准 → 渲染。 keyshot_preview_render 会嵌入 PNG，并在读取后删除临时文件。 只有在需要保存图像时才提供 outputPath。

制作产品渲染图

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 接受一个模型或一个已保存的场景。新模型默认使用导入构图选项； 现有场景会保留其设置，除非请求更改。在尚未发布的 main 上，对于没有基础场景的新模型， 标准视角相机会将世界空间场景边界适配到渲染宽高比，并在边缘留出 10% 的间距。 显式指定的距离、绝对相机坐标和基础场景会保留原有取景范围。这会包括场景中的所有几何体， 而不仅是主要产品；最终渲染前请先查看预览。已发布的 0.13.5 仍保留先前的取景方式。

比较同一对象上的材质

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.

名称重复时，请使用返回的 objectPath。材质名称取决于本地 KeyShot 库；请勿臆造。 请参阅材质规则。

在 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 接受一个文件或一个项目文件夹。后续调用时重复使用之前的 指纹；未更改的保存会返回 changed: false，且不会再次复制或渲染。这是显式同步， 而非自动后台监控。

渲染所有相机

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

要渲染所选相机，请使用 keyshot_batch_render；要渲染不同场景，请使用 keyshot_render_queue。

准备模型但不渲染

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.

如果只需要准备好的 .bip，请使用 keyshot_import_model。

调整镜头和环境

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.

如需针对性调整，请使用 keyshot_set_camera 和 keyshot_set_environment。

渲染质量

显式指定的尺寸和样本数会覆盖预设。maxTimeSeconds 会切换为基于时间的渲染， 且不能与显式指定的 samples 一起使用。 fieldOfView 和 focalLength 不能同时使用；相机的 position 和 lookAt 必须同时提供。质量预设无法保证最终外观。 省略 qualityPreset 时，较低层级的渲染工具会保留其现有默认值。

工具参考

从检查和产品渲染开始。其他工具提供针对性的控制； 完整参数请参阅生成的目录。

服务器还提供产品渲染 MCP 提示词和工作流 MCP 资源。 随附的 Agent 技能介绍设置、诊断和安全的工具选择。 这些是独立接口，并非额外的渲染工具。

相机和材质预设

随附的相机预设包括正面、背面、左侧、右侧、顶部、底部和等距视图。 自定义相机 JSON 支持 standardView，或绝对 position、lookAt 和可选的 up。支持对象和数组两种格式；请参阅预设文件。

材质预设引用本地 KeyShot 库名称或材质文件，而非随附的专有材质。服务器仅读取预设 JSON，不会对其进行编辑。 使用 KEYSHOT_CAMERA_PRESETS 和 KEYSHOT_MATERIAL_PRESETS 指定自定义文件。 请参阅材质分配和错误指南。

配置与安全

输入可以来自任何受信任的本地路径。默认情况下会拒绝输出路径遍历以及符号链接／联接点逃逸。 自动命名的产品输出发生命名冲突时会使用 -2、-3 等后缀；显式指定的路径不会被静默重命名。默认情况下，写入工具会拒绝覆盖现有文件。只有在有意替换不同输出时才设置 overwrite: true；即使如此，也绝不会替换本次请求的输入场景、模型、材质或环境，包括链接别名。预览和已保存场景的同步绝不会覆盖文件。场景和图像请使用不同的目标路径。建议使用场景副本。 每个服务实例中的 KeyShot 无界面任务会按顺序运行，以减少许可证和文件冲突；但不同 MCP 服务进程之间不会协调。

处理在本地进行。当 MCP 客户端中的 Agent 使用这些工具时，客户端可能会根据其实现和设置，将工具结果、场景元数据和预览图像发送给所选的模型提供商。KeyShot MCP 本身不会上传这些结果。处理机密工作前，请检查隐私设置。本工具不提供绕过许可证或任意执行 Python 的功能。请参阅安全。

问题与支持

能否编辑已打开的 KeyShot 窗口？ 不能。请先保存场景，再同步副本。 实验性桥接会使 Script Runner 保持活动状态并阻止交互；稳定版产品不包含该功能。技术说明。

更新的 MCP 支持是否意味着支持 ChatGPT Events 或 GUI？ 不是。稳定的 stdio 服务支持 2026-07-28 和旧版 2025-11-25 客户端。经过身份验证的远程 Events 传递是独立功能，尚未发布。请参阅升级说明。

如果设置、材质或渲染失败怎么办？ 运行 keyshot_status，查看失败的检查项和建议，核对本地材质名称，并尝试生成小尺寸预览。 不要将工具报错视为更改已完成。

• 安装与使用：讨论区。
• 可复现的错误：错误报告。
• 工作流需求：功能请求。
• 漏洞：私密报告。

分享日志前，请阅读支持说明。切勿公开发布私人场景、客户模型、凭据、许可证信息或机密渲染图。

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、许可证或官方材质库。

本版为 0.13.5： 集中加固输出保护、预览大小限制、发布隐私、 Windows 安装路径和启动诊断。下方安装示例使用此版本。 验证记录与正式版准备见验收清单， 版本变更见更新记录和升级说明。

把安装交给 Agent

将下面这段话发给能够修改客户端 MCP 配置的 Agent：

请用 npx -y [email protected] 将 KeyShot MCP 安装到我的 MCP 客户端。
找到本机 keyshot_headless.exe 的完整路径，设置 KEYSHOT_HEADLESS_EXE。
保留默认“文档/KeyShot MCP Outputs”输出目录，关闭外部输出。
按这个客户端实际支持的格式配置，重启或重新加载后运行 keyshot_status。
用普通设计师能理解的语言解释失败检查，不索取或上传许可证密钥。
不要上传或发布我的场景或保留的渲染文件。
如果要把保密场景的元数据或预览发送给模型服务，请先取得我的确认。

手动配置

下面是通用 mcpServers JSON 示例，不代表所有客户端都原样使用此格式。 可执行文件路径需要换成本机实际路径。

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

重启客户端，运行 keyshot_status，确认 ready: true。它检查可执行文件、输出目录 权限、bridge、预设以及最小 KeyShot 启动过程。

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

常用工作流

先预览，再正式出图

检查 C:\projects\speaker.bip，给我看预览，说明构图或材质问题。
先不要修改，也不要直接输出最终渲染，等我确认。

推荐顺序：状态检查 → 场景检查 → 预览 → 讨论 → 确认 → 正式渲染。 keyshot_preview_render 返回 PNG 后清理临时文件；需要保留图片时才填写 outputPath。

一句话准备产品出图

导入 C:\models\speaker.obj，居中贴地，用 Isometric 视角，保存副本，先给我看预览。
如果画面裁切了模型，先提出相机调整建议；确认后再按标准质量渲染。

keyshot_product_render 接受一个模型或一个已保存场景。新模型默认开启导入构图选项； 已有场景没有明确要求时保留原有设置。未发布的 main 中，不使用基础场景的新模型在 标准视角下会按世界坐标包围盒和输出宽高比调整取景，四边预留 10% 空间；显式距离、 绝对相机坐标和基础场景保留原有构图。包围盒包含场景全部几何体，不只主产品，正式出图 前仍需检查预览。已发布的 0.13.5 仍使用此前的取景逻辑。

只改一个对象的材质

检查场景并列出材质预设，找出金属对象，只把这个对象改为 Brushed Steel。
保持玻璃不变，保存副本，先展示预览，不要直接输出最终图。

同名对象应使用检查结果中的 objectPath。材质名称以本机材质库为准，不凭空填写。 具体规则见材质应用说明。

从 KeyShot 最近一次保存继续

我已把场景保存在 C:\projects\speaker。同步这个文件夹里最新的 .bip，
给我看预览，不要覆盖原场景。

keyshot_sync_saved_scene 接受文件或一个项目文件夹。再次调用时复用上次内容指纹； 没有新保存时返回 changed: false，不重复复制或渲染。它是显式同步，不是自动后台监控。

渲染全部相机

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

指定相机用 keyshot_batch_render；不同场景用 keyshot_render_queue。

只整理模型，不渲染

导入 C:\models\speaker.obj，居中贴地，调整相机观察点和环境。
保存场景副本，暂时不要渲染图片。

只需要整理好的 .bip 时使用 keyshot_import_model。

调整镜头与环境

把 Product Hero 相机设为 55 mm 焦距，将当前环境旋转到 45 度，
保存场景副本并给我看预览。

使用 keyshot_set_camera 和 keyshot_set_environment 分别调整相机与环境。

渲染质量

显式宽高和采样会覆盖预设值。maxTimeSeconds 改用限时渲染，不能与显式 samples 同时使用。fieldOfView 与 focalLength 互斥；position 与 lookAt 必须成对提供。 效果仍需检查，不能把质量预设理解为“保证最终效果”。 底层渲染工具未填写 qualityPreset 时，保留各自原有的默认行为。

工具参考

19 个工具按任务分组列在上方工具表，完整参数由代码自动生成在 工具目录。常用入口是 keyshot_status、keyshot_inspect_scene、 keyshot_preview_render、keyshot_sync_saved_scene 和 keyshot_product_render。

另有产品渲染 Prompt、工作流 Resource 和 Agent Skill。 它们用于指导流程，不是额外的渲染工具。无需记住全部名称，可直接描述设计需求。

相机与材质预设

内置七个相机视角：Front、Back、Left、Right、Top、Bottom 和 Isometric。 自定义相机 JSON 可填写 standardView，或绝对坐标 position、lookAt 与可选 up； 支持对象和数组格式，参见预设文件。

材质预设引用本机 KeyShot 材质库名称或材质文件，不附带专有材质资源。 服务只读取预设 JSON，不自动修改。自定义文件分别通过 KEYSHOT_CAMERA_PRESETS 和 KEYSHOT_MATERIAL_PRESETS 配置，材质规则及错误处理见材质应用说明。

配置与安全

输入可以来自任意可信本地路径。默认拒绝越界路径及软链接/目录联接逃逸。 产品工具自动命名的输出重名时使用 -2、-3 等编号，显式路径不被静默改名。 写入工具默认拒绝覆盖已有文件。只有确实要替换另一个输出文件时才设置 overwrite: true；即使开启，也不能覆盖本次调用的输入场景、模型、材质或环境文件， 包括指向它们的链接。预览与保存同步始终不覆盖。场景和图片必须使用不同路径，平时使用场景副本。 同一个服务实例内的 KeyShot 后台任务按顺序执行，以减少许可证和文件冲突； 多个独立 MCP 服务进程之间不共享这一排队机制。

处理在本机完成。MCP 客户端中的 Agent 使用工具时，返回的工具结果、场景元数据和 预览图可能根据客户端的实现与配置发送给所选模型服务。 KeyShot MCP 本身不主动上传 这些内容。保密项目请先核对隐私设置。项目不提供许可证绕过或任意 Python 执行。 更多说明见 SECURITY.md。

常见问题与支持

能控制正在打开的 KeyShot 窗口吗？ 不能。先保存，再同步副本。实验 Bridge 会持续占用 Script Runner，阻挡正常操作，因此没有作为稳定功能发布。 完整原因见 GUI 能力边界。

支持新 MCP 协议，就能用 ChatGPT Events 或实时控制吗？ 不能这样推断。 稳定 stdio 服务支持 2026-07-28 和旧 2025-11-25 客户端；远程鉴权与事件投递属于 尚未发布的独立集成，详见升级说明。

安装、材质或渲染失败怎么办？ 先运行 keyshot_status，查看失败检查和建议， 核对本机材质名称，再尝试小尺寸预览。不要把报错当成已经完成修改。

• 使用与安装：Discussions。
• 可复现错误：Bug 报告。
• 工作流建议：功能建议。
• 安全漏洞：私密报告。

分享日志前请阅读 SUPPORT.md，不要公开客户模型、私有场景、凭据、许可证或保密渲染图。

开发与路线图

环境准备与完整测试命令见贡献指南。CI 覆盖 Windows/Ubuntu 和 Node.js 20/24；Linux CI 不代表 KeyShot 已在 Linux 上实机可用。原有立方体保留为 自动 smoke test 夹具，npm run smoke:keyshot 只在已安装并合法授权 KeyShot 的机器运行。

后续重点：更多 KeyShot 版本和 macOS 实机验证，以及稳定 headless API 可用时的镜头 控制。实时 GUI 需要受支持的非阻塞接入方式，不采用长期阻挡窗口的脚本。

许可与非官方说明

代码采用 MIT License，第三方演示资产保留自己的许可。KeyShot 是 KeyShot ApS 和/或 KeyShot Inc. 的商标。本项目是独立开源社区项目，与官方无隶属、 认可或赞助关系。用户需单独安装并合法授权 KeyShot，不重新分发其专有软件或素材。 社区协作遵循行为准则。