Content
MCP
English |
A local MCP server for controlling KeyShot Studio through headless scripting.
It lets an AI app that supports MCPShot to inspect scenes, render images, import models, change materials, adjust cameras, set environments, and save scenes.
## Who This Isers who want AI-assisted KeyShot rendering.
- Developers who want a simple stdio MCP bridge for KeyShot.
- Teams that already have KeyShot licenses configured on their machines.
This project does not include KeyShot, does not bypass licensing, and does not store license keys.
## What It Can Do
- Check whether KeyShot headless can start.
- Inspect a `.bip` or supported KeyShot scene file.
- Render a scene to an image.
- Import a model into a scene.
- Apply a material to an object.
- Create or update a- Set an environment when the installed exposes that function.
- Save a scene to a new file.
## Example Workflows
- Batch render multiple camera views from one KeyShot scene.
- Test several material options on the same product model.
- Generate product hero images with consistent resolution and output naming.
- Import a model, apply a material preset, set a camera, and render in one AI instruction.
## Workflow
## Requirements
- with `keyshot_headless` support.
- Node.js 20 or newer.
- A valid KeyShot license already configured on the computer.
## Compatibility
| Platform | KeyShot Version | Node Version | Status |
| --- | --- | --- | --- |
| Windows 11 | KeyShot Studio 2025 / 14.1 | Node 22 | Tested |
| macOS | Not tested | - | Need contributors |
| Linux | Not tested | - | Need contributors |
## Install
```bash
npm install
npm run build
```
## Configure
Set the path to your KeyShot headless executable.
Windows PowerShell example:
```powershell
$env:KEYSHOT_HEADLESS_EXE="C:\Program Files\KeyShot Studio\bin\keyshot_headless.exe"
```
macOS/Linux shell example:
```bash
export KEYSHOT_HEADLESS_EXE="/Applications/KeyShot Studio.app/Contents/MacOS/keyshot_headless"
```
Then test startup:
```bash
npm run status
```
## MCP Client Example
Add a server like this to your MCP client config:
```json
{
"mcpServers": {
"keyshot": {
"command": "node",
"args": ["/absolute/path/to/keyshot-mcp/dist/index.js"],
"env": {
"KEYSHOT_HEADLESS_EXE": "/absolute/path/to/keyshot_headless"
}
}
}
}
```
For this computer, a ready-to-use Codex example is in:
```text
examples/codex.example.json
```
## Codex Configuration
For Codex, add a `keyshot` MCP server entry to your Codex MCP configuration and point it to the built server file:
```json
{
"mcpServers": {
"keyshot": {
"command": "node",
" ["/absolute/path/to/keyshot-mcp/dist/index.js"],
"env": {
"_HEADLESS_EXE":/path/to/keyshot_headless"
}
}
}
```
Use `x.example.json` as point and replace all paths with paths on your own computer.
Examples
```text
Render the current KeyShot scene into: front, 45-degree perspective, and top-down.1920x1080 resolution and save the outputs to the configured.
```
```text
Import the model file at /path/to/model.step, apply a brushed metal material to the main housing, 45-degree camera, a product hero image.
```
Inspect this KeyShot scene and summarize the available objects, materials, and render.
```
## Environment Variables
- `KEYSHOT_HEADLESS path to `keyshot_headless` or `keyshot_headless.exe`.
- `KEYSHOT_OUTPUT_DIR`: default output folder for renders.
- `KEYSHOT_LICENSE optional KeyShot headless license arguments. Empty by default.
-SHOT_TIMEOUT_MS`: in milliseconds. Default: ``.
## MCP Tools
- `keyshot_status`
- `keyshot_inspect_scene`
- `keyshot_render`
- `keyshot_import_model`
- `keyshot_apply_material`
- `keyshot_set_camera`
- `keyshot_set_environment`
keyshot_save_scene`
Each tool returns JSON with:
- `ok`
- `data`
- `outputFiles`
- `warnings `keyshotStdoutTail`
- `error`
## Notes
KeyShot's Python ` API changes across versions. This server keeps the MCP interface stable and returns a clear error when anShot version does not expose a requested headless function.
- [ ] all cameras in a scene [ ] Material preset library
] Camera preset templates [ ] Render queue status [ ] Safer output
- [ ] More tested KeyShot versions
- [ verification
- [ ] Claude Desktop / Cursor / config examples
## License
---
# Tool List
## Star History
is generated from GitHub stargazer data and refreshed by GitHub Actions.
