Use Silhouette with AI

Silhouette AI operations use the official Blender Lab MCP on a dedicated local bridge. Follow the customer setup below; no development-workstation paths are required. Keep this automation scene separate from your artist session.

All everyday new-Folk operations use stylized_creator.agent_api.execute(request). The artist sidebar and agent API call the same scene operations. The interface is local, bounded and model-independent: no arbitrary Python command endpoint, no network listener, telemetry or bundled chatbot.

MCP setup on your computer

The artist add-on works without MCP. AI control needs both parts of the official Blender Lab MCP: its Blender extension and its Python server. This is a separate installation, not a bundled Silhouette dependency. Tested here: extension 1.0.3 and Python server 1.0.2.

1. Install Blender 5.2.2 LTS, Python 3.11 or later, and Git. From the official page, install and enable the MCP extension by Blender Lab. Use its Install from Disk download or add the Blender Lab extension repository as described there.
2. Download the official server source, or install its Python package into a local environment. The official server installation instructions specify the source below. Example PowerShell commands (choose your own existing tools folder; no drive letter is required by Silhouette):

``powershell python -m venv E:/BlenderTools/BlenderMCP/.venv E:/BlenderTools/BlenderMCP/.venv/Scripts/python.exe -m pip install "git+https://projects.blender.org/lab/blender_mcp.git#subdirectory=mcp" ``

1. Open a separate Blender instance for automation. In the MCP extension's preferences, set host 127.0.0.1, port 9896, and start its server. Reserve this scene for Silhouette commands; create starts a new empty scene there. Keep artist work in a different instance. If that port is occupied, choose an unused port and use the same number in SILHOUETTE_MCP_PORT below.
2. Extract the complete Silhouette product bundle. Keep automation beside stylized_creator and its packed assets. Configure your MCP client with the following paths, replacing all example paths with yours:

{
  "mcpServers": {
    "silhouette": {
      "command": "E:/BlenderTools/BlenderMCP/.venv/Scripts/python.exe",
      "args": ["E:/BlenderTools/Silhouette/automation/silhouette.py", "--mcp"],
      "env": {
        "BLENDER_MCP_PYTHON": "E:/BlenderTools/BlenderMCP/.venv/Scripts/python.exe",
        "SILHOUETTE_MCP_PORT": "9896"
      }
    }
  }
}

1. Restart/reconnect the MCP client and ask it to call Silhouette's catalog. Then create a Folk and save it to an existing folder you own. If connection fails, confirm the extension's server is running on the matching loopback host/port and the configured Python environment can import blmcp and mcp. The local workstation's Start-BlenderMCP.ps1 is a convenience helper, not a required customer file or part of the product bundle.

The client launches the adapter; the already-running official Blender MCP bridge handles each request. Rendering can take longer than editing. Commands time out after ten minutes. Do not edit a blend file while another Blender session is saving it. The optional --blender argument records a Blender executable path for the worker environment; it does not start the bridge for you.

Ask your assistant: “Use Silhouette's catalog, create a Quinn Folk, discover its controls, make the face a little wider, show me a face render, and save an editable copy to my output folder.” Give it an absolute path to an existing folder. Inspect the rendered image before exporting.

JSON requests

For a standalone terminal, set BLENDER_MCP_PYTHON to the Python executable from step 2 and SILHOUETTE_MCP_PORT to the bridge port in that terminal too; MCP-client environment settings do not carry over to unrelated terminals. Save one request to a JSON file and run:

python automation/silhouette.py --request request.json

Create and save:

{"action":"create","rig":"Quinn","save_to":"E:/BlenderTools/Silhouette/output/my-folk.blend"}

Read controls from that file:

{"action":"state","project":"E:/BlenderTools/Silhouette/output/my-folk.blend"}

Edit a working copy:

{"action":"set","project":"E:/BlenderTools/Silhouette/output/my-folk.blend","values":{"sc_face_width":0.2,"smile":0.15},"save_to":"E:/BlenderTools/Silhouette/output/my-folk-v2.blend"}

Select a review camera and save it, then request a render from that saved file. Use export with an absolute .glb or .fbx path for interchange. recipe returns JSON settings; apply_recipe takes them in a recipe object.

Expression and recipe contract

State and look recipes use schema 2 for eye revision 2. Each control reports its kind: morph, texture (Blink), or morph+texture (Tired). Read the state before editing; all 49 channels remain available. Blink/Tired updates are local and the current painted eye look is packed into saves and GLB/FBX exports. It is a static texture snapshot, not an exported animated eyelid channel. Earlier cap-based recipes are rejected with a compatibility message; earlier blend files retain their own representation.

Command reference

For any edit, add save_to to persist the modified scene. Otherwise it is temporary and is not written to the source file. Existing outputs are refused unless overwrite is explicitly true. Output folders must already exist. Unknown controls, non-finite values and out-of-range edits are rejected before any control changes. The adapter reads local files as the current OS user; configure it only in a trusted local client, with access limited to the project folders you intend.

Inside Blender Python

from stylized_creator.agent_api import execute
execute({"action": "create", "rig": "Quinn"})
state = execute({"action": "state"})
execute({"action": "set", "values": {"sc_face_width": 0.2}})

Blender's own Python console is an advanced local option. The bounded Silhouette adapter does not accept arbitrary code. The underlying official Blender Lab MCP also exposes advanced code-execution tools; configure that separate server only in a trusted local client. The new API works on new Folk scenes; specialist legacy hair/sculpt/export operations retain their existing Blender operator interfaces.

Development workstation notes

These paths and helpers describe the development workstation, not a required customer installation.

All Blender agent work uses the official Blender Lab MCP. On this workstation it is installed at E:/BlenderTools/BlenderMCP; Codex and Claude are configured to use it. Start a bridge with Start-BlenderMCP.ps1. Inspect the connected scene before editing. Use a separate port for concurrent projects and keep artist files intact.

The bounded Silhouette adapter described above routes its jobs through the official MCP tool execute_blender_code on an owned bridge at port 9896. Start it with Start-BlenderMCP.ps1 -Port 9896; set SILHOUETTE_MCP_PORT to use another dedicated port. Do not point it at a bridge used by another project. The human source launcher OpenSilhouette.ps1 opens a separate artist session with the official bridge at port 9882 (or -McpPort), preserving saved global preferences. Connect the official client to that port to inspect the live artist scene. The bounded adapter stays on its separate automation bridge and does not edit the artist session.

It does not launch Blender scripts directly. Install the official MCP Python package and set BLENDER_MCP_PYTHON to that environment's Python executable on another machine.