KeyShot

keyshot-mcp

通过模型上下文协议（MCP），使用 Claude Code 控制已打开的 KeyShot Studio 2026 窗口。

状态：原型。 这些工具可以运行，也有测试，但项目依赖 KeyShot 的脚本 API，而该 API 可能会发生变化。欢迎告知我们你的使用方式以及遇到的问题：提交 issue 或参与讨论。

演示播放速度是实际速度的 3 倍。

Claude Code ⇄ MCP server keyshotmcp (Python 3.12, stdio)
            ⇄ TCP 127.0.0.1:1998, 4-byte length + JSON, token
            ⇄ MCP start.py (in KeyShot, timer on the UI thread)

桥接程序在 KeyShot 内运行。服务在 Claude Code 中运行。两者仅在本地计算机上通信。

要求

项目	版本
KeyShot Studio	15.1（2026）或更高版本。已在 2026.2 Pro（15.1.2.7）中测试。
Python	3.12 或更高版本，Windows
mcp	1.30.0
Claude Code	任意近期版本

安装

从 PyPI 安装

从 1.1.0 版本起，keyshot-mcp 是一个 Python 软件包。使用 uv：

uvx keyshot-mcp install-addin
claude mcp add keyshot -- uvx keyshot-mcp

install-addin 会将两个桥接脚本复制到 %PUBLIC%\Documents\KeyShot Studio\Scripts（或 --dir 指定的文件夹）。然后重启 KeyShot。

作为 Claude Code 插件安装

从 1.1.0 版本起，此仓库也提供 Claude Code 市场。keyshot 插件通过 uvx 启动服务，因此必须安装 uv。

/plugin marketplace add lfoletti/keyshot-mcp
/plugin install keyshot@keyshot-mcp

然后运行一次 /keyshot-install-addin，并重启 KeyShot。

从发布压缩包或仓库安装

每个发布版本都包含 keyshot-mcp-<version>-windows.zip，其中已填充 libs/。解压后，从步骤 3 开始。若不使用压缩包，则从步骤 1 开始。

1. 克隆仓库：

   git clone https://github.com/lfoletti/keyshot-mcp.git
   

2. 在 libs 文件夹中安装 mcp。run.py 会从该文件夹加载它。

   py -3.12 -m pip install --target libs mcp==1.30.0
   

3. 将 addin\Scripts\MCP start.py 和 MCP stop.py 复制到 C:\Users\Public\Documents\KeyShot Studio\Scripts\。
4. 重启 KeyShot。KeyShot 只会在启动时读取 Scripts 文件夹。
5. 将服务添加到 Claude Code：

   claude mcp add keyshot -- py -3.12 -I -S C:\path\to\keyshot-mcp\run.py
   

6. 确认导入正常：

   py -3.12 -I -S run.py --check
   

   输出应显示 keyshot : imports ok 和 33 个工具。

使用

1. 在 KeyShot 中，打开 窗口 > 脚本控制台 > 脚本。
2. 选择 MCP start，然后点击 运行。控制台会显示 Pont KeyShot actif sur 127.0.0.1:1998。
3. 在 Claude Code 中输入 /mcp。确认 keyshot 已连接。
4. 向 Claude 提出请求，例如：
   • “显示场景并列出材质。”
   • “为瓶盖应用拉丝铝材质，然后渲染一张 1920 × 1080 的图像。”

若要停止桥接程序，请运行脚本 MCP stop，或关闭 KeyShot。 若要更新桥接程序，请复制新文件，然后使用工具 reload_bridge。

工具

分组	工具
场景	keyshot_status、get_scene_info、get_scene_tree、list_objects、set_visibility、screenshot、save_scene
摄像机和环境	list_cameras、set_camera、fit_camera、list_environments、set_environment、set_realtime
材质	list_materials、get_material、list_library_materials、assign_material、set_material_parameter、rename_material、undo_material_changes、commit_material_changes、save_material_to_library
材质图	add_material_node、connect_material_nodes、disconnect_material_input、remove_material_node
渲染	render_image、render_status、wait_for_render、view_image
桥接程序	lux_functions、reload_bridge、execute_python（默认关闭）

两个 MCP 提示词会向 Claude 提供操作方法：

提示词	用途
keyshot_strategy	如何在 KeyShot 中操作而不破坏场景。
keyshot_materiaux	如何根据 CMF 表（颜色、材质、表面处理）或描述制作材质：物理值、颜色、节点配方。

颜色：[r, g, b] 为线性值（0-1）。#RRGGBB 为 sRGB：桥接程序会将其转换为线性值。

设置

可选文件：%LOCALAPPDATA%\keyshot-mcp\pont-config.json。

{"execute_python": false, "dossier_sorties": "C:\\path\\to\\outputs"}

设置	效果
execute_python	设为 true 可启用工具 execute_python。默认值为 false。
dossier_sorties	用于存放屏幕截图、渲染图和场景备份的文件夹。
dossiers_textures	桥接程序可从中读取纹理图像的其他文件夹列表。KeyShot 的纹理库和 dossier_sorties 始终允许访问。
KEYSHOT_MCP_PORT	环境变量。桥接程序端口。默认值为 1998。
KEYSHOT_MCP_TIMEOUT	环境变量。服务超时秒数。默认值为 60。
KEYSHOT_MCP_EXECUTE_PYTHON	环境变量。设为 1 可启用 execute_python。

桥接程序会在同一文件夹中写入 pont-actif.json（端口、令牌、KeyShot PID）和 pont.log。

安全性

• 桥接程序仅侦听 127.0.0.1。每个请求都必须包含 pont-actif.json 中的令牌。
• execute_python 默认关闭。只有本地设置才能启用它。
• 工具只会编辑桥接程序创建的副本中的材质图。
• set_camera 不会丢弃尚未保存的摄像机视图。
• save_scene 会保留旧 .bip 文件的副本。

测试

测试使用伪造的 lux 模块。无需安装 KeyShot。

cd tests
py -3.13 test_pont.py
py -3.13 test_serveur_mcp.py
py -3.13 test_cli.py
py -3.13 test_publication.py
py -3.13 test_plugin.py
py -3.13 test_dev_version.py

test_pont.py 包含 87 项桥接程序测试。test_serveur_mcp.py 包含 9 项端到端测试。test_cli.py 测试命令 keyshot-mcp。test_publication.py 和 test_plugin.py 检查 PyPI、MCP 注册表和插件文件，并确认此 README 与代码一致。test_dev_version.py 测试 TestPyPI 版本工具。essai_*.py 文件需要 KeyShot 处于打开状态。

test_serveur_mcp.py 会使用运行测试的 Python 启动服务。如果 libs 中的包适用于其他 Python 版本，请将 KEYSHOT_MCP_PYTHON 设为相应的 python.exe。

贡献

请阅读 CONTRIBUTING.md 和 CODE_OF_CONDUCT.md。

状态

keyshot-mcp 是一个可运行的原型，已在 Windows 上使用 KeyShot Studio 2026.2 Pro 进行测试。

• 桥接程序使用 KeyShot 脚本 API（lux）。新的 KeyShot 版本可能会更改此 API。
• KeyShot 未来版本可能会加入与 Claude 的集成。届时本项目可能会停止维护。
• 反馈优先于新功能。请使用 Bug 和 Feedback 问题模板。

免责声明

keyshot-mcp 是一个独立项目，与 Luxion 或 KeyShot 无关；截至目前，Luxion 也未为其背书或提供赞助。KeyShot 是 Luxion 的商标。

许可证

MIT