Ceratops-Blender-MCP is a local versioned Blender production server for character and shot pipelines, exposing read-only inspection, immutable stage creation, review/approval, rendering, packaging, and job monitoring.
Inspect project state, list assets, inspect exact versions, compare artifact hashes, and validate character lineage.
Create immutable character stages: reference import, blockout, mesh, retopology, UV/materials, groom, rig, face rig, and review renders.
Create immutable shot stages: layout, assembly from exact character versions, camera, lighting, blocking animation, lip sync, secondary motion, preview renders, and final renders.
Promote exact versions at named review gates without changing bytes, and archive versions while retaining files.
Package exact asset or episode versions into versioned ZIPs.
Read persistent job status; the schema also exposes cancel_job and resume_job.
Note: the schema requires request_id on writes and includes job cancellation/resumption, conflicting with the README’s stated v1 contract of no caller request IDs and no job continuation/mutation.
Drives a local Blender CLI to run versioned character and shot production: creating immutable character stages (reference import, blockout, mesh, retopology, look development, groom, rig, face rig) and shot stages (layout, assembly, camera, lighting, blocking animation, lip sync, secondary motion), rendering review images, previews, and final frame sequences, and packaging versioned asset/episode ZIPs. Includes read-only inspection and version comparison, validation, explicit review gates and approvals, and persistent job status/cancel/resume, all without invoking arbitrary Blender Python.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Ceratops-Blender-MCP Create a character mesh for hero from blockout v0003, request_id hero_mesh_01"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Ceratops-Blender-MCP is a local, goal-oriented MCP server for versioned Blender character and shot production. Ceratops-Blender-Kit is its companion workflow skill. The server exposes fixed production transitions, not arbitrary Python or an alternative low-level Blender console.
This v1 is a working local control plane and Blender CLI integration. It creates
simple production-ready starting structures, versioned .blend files, review
renders, frame sequences, and ZIP packages. Artistic refinement remains a human
and agent workflow; the low-level Blender MCP can still be used separately when
an approved version needs bespoke editing.
Skill | Purpose |
| Orchestrate versioned Blender character and shot production, including exact-source selection, review gates, approvals, and packaging. |
Install the workflow skill from a clean checkout with
uv run --project scripts --locked python scripts/deploy-skills.py.
The locked scripts project supplies the bootstrap dependencies; the installer
prepares the skill runtime separately.
Related MCP server: blendermcp
Read-only project and asset inspection, exact version comparison, and character content checks.
Immutable character stages: reference import, blockout, mesh, retopology, look development, groom, rig, face rig, and review renders.
Immutable shot stages: layout, assembly from exact character versions, camera, lighting, blocking animation, lip sync, secondary motion, preview, and final frame sequences.
Explicit appearance, groom, rig, facial-expression, and animation review gates. Promotion records approval without changing version bytes.
Versioned asset and episode ZIP packages.
Current-worker status with fresh monitoring identifiers.
Repeated desired-state actions reuse matching completed output.
Archival without permanent production-version deletion.
Write tools take ordinary production inputs. A fresh invocation checks the actual project, selected versions and lifecycle state; it never reads a failed job to decide what to execute. A still-live matching operation shares its worker. There are no caller request IDs, job continuation or job mutation operations.
Requirements:
Windows x64 CPython 3.14
Blender available as blender on PATH, or an absolute binary path in
CERATOPS_BLENDER_EXECUTABLE
$server = "mcp-servers/ceratops_blender_mcp"
uv sync --project $server --extra dev --locked
$env:CERATOPS_BLENDER_EXECUTABLE = 'C:\Program Files\Blender Foundation\Blender 4.5\blender.exe'
uv run --project $server --locked ceratops-blender-mcpThe source entry point uses MCP stdio. After managed deployment, a host should
launch %USERPROFILE%\.codex\mcp\ceratops-blender-mcp\bin\ceratops-blender-mcp.cmd --mcp and pass the Blender executable through its environment when Blender is
not on PATH.
The server uses the maintained MCP Python SDK v2 (mcp>=2,<3) and its
MCPServer API. The package name and Python module use lowercase ecosystem
forms; the server identity presented to users is Ceratops-Blender-MCP.
Run the standalone monitor in a PowerShell console:
powershell.exe -NoProfile -File .\scripts\limit-blender-ram.ps1It runs until Ctrl+C, monitors existing and newly started blender.exe processes,
and adjusts their combined pageable working-set allowance to target 1.5 GiB of
available system RAM. Windows can page Blender's larger allocations to disk;
the monitor does not impose a total allocation limit. The optional parameters
-AvailableGiB, -IntervalSeconds, and -SettleSeconds default to 1.5, 1, and
5.
Caps respect existing hard minimum/maximum limits, use a 64 MiB per-process floor,
and allow time for paging between adjustments. Other applications, shared pages,
and nonpageable memory can prevent the target from being reached; it is not a
guaranteed reserve. Expect slower rendering under memory pressure.
Keep the console open. Normal stopping restores the prior sizes and enforcement flags when they still belong to this monitor. Force-killing the monitor bypasses cleanup and leaves its last limits on surviving Blender processes; a subsequent monitor run can adjust them again, but cannot recover originals lost with the killed process. Limits also disappear when Blender exits. Access or job-object restrictions are reported per process, without changing privileges or job limits. Only one monitor may run on the computer. The script creates no runtime files, logs, startup entries, or scheduled tasks and runs no model calls.
Read tools never initialize a project or alter production state:
inspect_project, list_assets, inspect_asset
compare_asset_versions, validate_character
get_job_status
Version and lifecycle writes:
import_character_reference, promote_version, archive_version
create_character, create_character_mesh, retopologize_character
create_uv_and_materials, groom_character, rig_character
build_face_rig, render_character_review
create_shot, assemble_shot, setup_camera, light_shot
animate_shot, sync_lips, add_secondary_motion
render_shot_preview, render_shot_final
package_asset, package_episode
A Blender-producing operation reuses matching completed output or creates a
new vNNNN directory. Callers must
pass exact source versions; the server does not silently choose “latest.”
Downstream gated tools accept only the exact version approved at the required
gate. render_shot_final, for example, requires the selected preview version to
have passed the animation gate.
The source repository owns code, tests, documentation, and the skill. Each caller-selected Blender project owns its runtime data:
<project>/.ceratops-blender/
project.json
state.lock
characters/<id>/versions/vNNNN/
characters/<id>/events/
shots/<id>/versions/vNNNN/
shots/<id>/events/
deliveries/<id>/versions/vNNNN/
jobs/job_<worker-uuid>.jsonA version request is written first, output bytes are written into that reserved
directory, and record.json is written last. Completed version records and
artifacts are immutable. A failed partial may retain a bounded error until the
next production call discards abandoned partials under the project production
lock. Partial numbers may be reused; completed version identities never are.
Promotion and archive events describe current business state; repeating the
current choice is a no-op, while selecting a prior version after another
promotion records the new choice.
Projects permit 25 active versions per entity by default. Creation stops at the limit until the caller archives an older version; archived production data is retained because v1 offers no permanent-delete tool. Job history is operational data: active jobs are always retained and the 100 most recently updated terminal job records are kept. Atomic control writes remove their temporary sibling on success or failure. Blender subprocess output is held only in bounded memory and is not persisted as an unbounded log.
The repository's single lifecycle contract is sdlc/sdlc.yml. It declares the
real validation and test entry points created by current Ceratops compatibility
tooling. Run them through the repository lifecycle operation runner, or use the
narrow developer commands while editing:
uv run --project mcp-servers/ceratops_blender_mcp --extra dev --locked ruff check .
uv run --project mcp-servers/ceratops_blender_mcp --extra dev --locked mypy
uv run --project mcp-servers/ceratops_blender_mcp --extra dev --locked pytestTests use a recording Blender runtime so versioning, gating, packaging, and MCP
contracts are exercised without pretending that a local Blender installation
was rendered in CI.
mcp-servers/ceratops_blender_mcp/tests/test_blender_integration.py adds a real
Blender smoke case and runs only when CERATOPS_BLENDER_EXECUTABLE is explicitly
set.
GitHub source publication and Ceratops-managed local deployment are supported; no PyPI release or hosted Blender service is provided.
The unfinished exact-artifact lifecycle described in the Ceratops refactor plan is not implemented here. There are no fabricated build receipts, artifact declarations, delivery actions, or deployment claims.
V1 does not permanently delete production versions, invoke arbitrary Blender Python, synthesize high-end character art, run a render farm, or coordinate distributed Blender workers.
Internal shutdown is cooperative around the owned local Blender subprocess. A machine-level crash can leave Blender work that the operating system must end; the future Ceratops worktree process-group design is not claimed here.
See docs/DESIGN.md for component boundaries and failure
behavior, and skills/ceratops-blender-kit/SKILL.md
for the user-facing production workflow.
Add bounded procedural secondary motion in a new shot version.
Inputs: shot_id (required), request_id (required), project_root (required), source_version (required), +1 more. Returns: object
Create a deterministic blocking-animation version.
Inputs: shot_id (required), request_id (required), project_root (required), source_version (required), +2 more. Returns: object
Archive an unpromoted version while retaining every file and record.
Inputs: reason (required), version (required), asset_id (required), asset_type (required), +2 more. Returns: object
Assemble exact character versions into a new shot version.
Inputs: shot_id (required), request_id (required), project_root (required), asset_versions (required), +1 more. Returns: object
Create facial shape keys from a rig-approved exact source version.
Inputs: request_id (required), character_id (required), project_root (required), source_version (required), +1 more. Returns: object
Request cancellation of an exact queued or running production job.
Inputs: job_id (required), project_root (required). Returns: object
Compare the metadata and artifact hashes of two exact asset versions.
Inputs: asset_id (required), asset_type (required), left_version (required), project_root (required), +1 more. Returns: object
Create a deterministic character blockout, optionally from an exact reference version.
Inputs: request_id (required), character_id (required), project_root (required), style, +3 more. Returns: object
Create a mesh version from one exact character version.
Inputs: request_id (required), character_id (required), project_root (required), source_version (required), +1 more. Returns: object
Create a new shot layout with an explicit frame range.
Inputs: shot_id (required), request_id (required), project_root (required), fps, +2 more. Returns: object
Create UVs and a material in a new look-development version.
Inputs: request_id (required), character_id (required), project_root (required), source_version (required), +2 more. Returns: object
Read the persistent status and result of a long production job.
Inputs: job_id (required), project_root (required). Returns: object
Create a groom from an appearance-approved exact source version.
Inputs: request_id (required), character_id (required), project_root (required), source_version (required), +2 more. Returns: object
Copy reference images or files into a new immutable character version.
Inputs: request_id (required), character_id (required), project_root (required), reference_files (required). Returns: object
Read one asset's lifecycle state or one exact immutable version.
Inputs: asset_id (required), asset_type (required), project_root (required), version. Returns: object
Read project counts, configuration, and active-job state without modifying it.
Inputs: project_root (required). Returns: object
Create a lit shot version using a fixed production preset.
Inputs: shot_id (required), request_id (required), project_root (required), source_version (required), +2 more. Returns: object
List character and shot identities plus their explicit versions.
Inputs: project_root (required), asset_type, include_archived. Returns: object
Package one exact character or shot version into a versioned ZIP.
Inputs: version (required), asset_id (required), asset_type (required), request_id (required), +1 more. Returns: object
Package caller-selected exact shot versions into a versioned episode ZIP.
Inputs: episode_id (required), request_id (required), project_root (required), shot_versions (required). Returns: object
Approve an exact version at a named review gate without changing its bytes.
Inputs: gate (required), version (required), asset_id (required), reviewer (required), +4 more. Returns: object
Render a review artifact in a new version for an explicit approval gate.
Inputs: request_id (required), character_id (required), project_root (required), source_version (required), +3 more. Returns: object
Render an animation-approved source into a new final-render version.
Inputs: shot_id (required), request_id (required), project_root (required), source_version (required), +4 more. Returns: object
Render a review sequence into a new preview version.
Inputs: shot_id (required), request_id (required), project_root (required), source_version (required), +4 more. Returns: object
Resume failed, cancelled, or interrupted work under the same stable job ID.
Inputs: job_id (required), project_root (required). Returns: object
Create a non-destructive retopology version with a target face budget.
Inputs: request_id (required), character_id (required), project_root (required), source_version (required), +1 more. Returns: object
Create a rig from a groom-approved exact source version.
Inputs: request_id (required), character_id (required), project_root (required), source_version (required), +1 more. Returns: object
Create a camera version from one exact shot source.
Inputs: shot_id (required), request_id (required), project_root (required), source_version (required), +3 more. Returns: object
Apply explicit frame/value mouth cues to an exact shot version.
Inputs: cues (required), shot_id (required), request_id (required), project_root (required), +1 more. Returns: object
Read and validate exact character lineage plus recorded artifact hashes.
Inputs: version (required), character_id (required), project_root (required). Returns: object
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 30 tools
Most tools have distinct purposes, but render_character_review, render_shot_preview, and render_shot_final could be confused despite different targets and gates. Creation tools (create_character, create_shot, setup_camera, etc.) are clearly differentiated by noun. Some overlap exists but descriptions help.
All tool names follow a consistent verb_noun pattern, with verbs like create, inspect, list, compare, promote, archive, package, render, validate, get, cancel, resume. No mixed conventions or vague names.
With 30 tools, the set is large and may overwhelm an agent or indicate over-specialization. While each tool has a clear purpose, the count feels heavy for a typical MCP server, and some tools could potentially be merged (e.g., render_* into a parameterized render tool).
The tool surface covers a comprehensive production lifecycle from creation, inspection, validation, promotion, packaging, rendering, to job management (status, cancel, resume). No obvious CRUD or lifecycle gaps for the domain of character and shot production.
Hosted video MCP server for branded explainers and reference-driven edits.
Build, test, publish, and run Kovca workflows from AI agents over remote MCP.
Remote MCP for Kiro release readiness, evidence binders, signoff, and CI approval receipts.
Create, browse, remix, collaborate on, and run durable AI workflow nodes from MCP hosts.
