clo3d-mcp
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., "@clo3d-mcp Change the fabric of the dress to red"
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.
CLO MCP
Describe a garment change. Inspect the result in CLO. Keep editing.
CLO MCP connects a local MCP-compatible AI assistant to CLO's Python API. It provides tools for inspecting a project, editing patterns, sewing, changing fabrics, simulating, taking snapshots, and saving checkpoints. It also includes an experimental parametric drafting engine for dresses, tops, and skirts.
v0.1.0-alpha.1 · Experimental · macOS · MIT
This is an independent community integration, not an official CLO product. You need your own licensed installation of CLO and a local MCP client. CLO, avatars, fabrics, commercial reference images, Blender, and inZOI assets are not included.
Start here
Install and connect: Beginner setup guide
See what to ask: Example prompts
Recover from errors: Troubleshooting
Understand the release: Release notes and validation record
Publish your own copy: GitHub publishing guide
Related MCP server: clo3d-mcp
What it can do
Workflow | Tools / behavior |
Inspect a project | Scene, pattern, fabric, avatar, sewing, and arrangement information |
Edit garments | Create/delete patterns, edit points, configure supported pattern properties, sew pieces |
Change materials | Apply locally installed fabrics, change color, assign texture maps |
Review the result | Simulate, reset arrangement, export snapshots, inspect the 2D view |
Save work | Save/open projects, export supported formats, save and restore checkpoints |
Draft a starting point | Preview a dress/top/skirt plan offline, then build and refine it in CLO |
Discover the installed API | Search live names and docstrings, inspect overloads, make structured API calls |
Advanced operations | Execute Python inside CLO with |
Optional Mac UI fallback | Accessibility inspection, screenshots, and input tools with separate permissions |
The drafting engine does not automatically recreate an arbitrary photograph, produce production-approved sewing patterns, or guarantee fit on every avatar. Its built-in garment categories are dresses, tops, and skirts; trousers/jorts need custom work. Mesh imports may appear in 3D without editable 2D sewing patterns. The UI fallback is experimental and has not received comprehensive live validation.
Quick start for users familiar with Terminal
Download and extract the source release, open Terminal in its folder, then:
uv sync --no-editable --python 3.12 --locked
uv run --no-editable python scripts/print_setup.pyThe helper prints the correct paths for your machine, a CLO registration command, a direct bridge-start command, a Codex CLI command, and generic MCP JSON. It does not edit settings or start applications. Follow the full guide to use those outputs.
In CLO, start the bridge once per session. In the assistant, ask:
Use
clo_statusand tell me whether the bridge is connected. Then inspect the current scene without changing it.
Start on a duplicate project. Keep tool approvals enabled in your MCP client. Read the trust model: the bridge intentionally allows local code execution and is not a sandbox.
Compatibility and evidence
The original integration has been used with CLO 2026.1.224 on macOS, whose embedded Python is 3.11. The release's external server is validated locally with Python 3.12. The package declares Python 3.11+; CI covers 3.11 and 3.12 on macOS and Linux for offline tests only. This is not a claim that CLO runs on Linux or that the bridge works on Windows.
The bridge pumps CLO's Qt event loop using native symbols. It now refuses to serve if it cannot find the event pump, rather than deliberately freezing the UI. Native CLO operations can still crash or hang the application. A failed or timed-out mutation may already have changed the scene: inspect before retrying.
See VALIDATION.md for what was actually checked and what remains unverified. This first release is a pre-release, not a stability guarantee.
How it works
Your local AI/MCP client
| stdio (MCP)
v
clo3d-mcp Python server
| JSON lines over 127.0.0.1:5077
v
Python bridge inside CLO, on its UI thread
| CLO Python API
v
Your CLO projectThe client launches the server; you launch the bridge inside CLO. Both run on the same machine and account. No cloud bridge or public HTTP endpoint is provided. Tool responses and screenshots go to your MCP client, whose own AI-provider data policies still apply.
Development
uv sync --no-editable --python 3.12 --locked
uv run --no-editable pytest -q
uv run --no-editable python tests/smoke_stdio.py
uv buildThe smoke test initializes MCP and previews a garment without connecting to CLO. tests/verify_live.py is a separate, read-only API check requiring a running bridge. Do not run garment mutations against someone's active work as a test.
Available Tools
48 toolsarrangement_pointsA
List the avatar's arrangement points (names used to place pattern pieces on the body).
Inputs: no named parameters.
avatar_listB
Avatars in the scene and the .avt files available in the CLO asset library.
Inputs: no named parameters.
avatar_loadC
Load an avatar by alias (mia, luka, female mannequin, male mannequin, melody, oliver), file name or path.
Inputs: replace, name_or_path.
avatar_measurementsA
Body measurements (mm) of the avatar in the scene, used for drafting. Source: CLO's measurement API (needs the Avatar Editor opened once per session in CLO), a cache, or an approximation from the avatar mesh.
Inputs: refresh.
checkpoint_listB
List saved checkpoints.
Inputs: no named parameters.
checkpoint_restoreA
Reload a checkpoint saved with checkpoint_save (replaces the scene).
Inputs: name (required).
checkpoint_saveA
Save the current project as a named checkpoint (.zprj under ~/.clo3d-mcp/checkpoints) so a failed edit or seam can be undone with checkpoint_restore.
Inputs: name.
clo_api_callA
Call any public function discovered in clo_api_catalog, or read a constant. Read its live documentation first. JSON supports {$type:'ApiTypes.TypeName',args:[],fields:{...}}, {$enum:'ApiTypes.Enum.Member'}, and {$handle:'id'}. Non-JSON return objects get session handles. A false result is NOT success. Never retry a timed-out mutation blindly; inspect scene/UI first. Use checkpoint_save before risky scene edits.
Inputs: name (required), args, kwargs.
clo_api_catalogA
Discover functions, types and constants in the RUNNING CLO version. Paged; no API functions are executed. Search names and docstrings. Modules include rest_api and ApiTypes. Follow next_offset for full coverage.
Inputs: limit, query, module, offset.
clo_api_describeA
Live docstring/overloads and class fields for a qualified name, e.g. pattern_api.GetPatternCount or ApiTypes.ImportExportOption. Documents the running version.
Inputs: name (required).
clo_api_docB
Read live documentation for a CLO function. Prefer a qualified name such as pattern_api.GetPatternCount.
Inputs: function_name (required). Returns: result
clo_api_releaseA
Release native API object handles when finished; handles expire when CLO restarts.
Inputs: handles (required).
clo_api_searchA
Search names and docstrings in the running CLO API. Requires the bridge. Use clo_api_catalog for pagination.
Inputs: query (required), limit. Returns: result
clo_control_guideB
Routing guide for CLO functions absent from the API, including desktop prerequisites and verification.
Inputs: no named parameters.
clo_launchA
Launch CLO (macOS). Passing -python clo_bridge.py is attempted, but CLO 2026.1 did not run it at startup in testing, so after CLO is up start the bridge with the menu item Plugins > start_bridge (or ask the user to click it).
Inputs: with_bridge. Returns: result
clo_run_pythonA
Run Python inside CLO with the CLO API modules pre-imported (import_api, export_api, fabric_api, pattern_api,
utility_api, rest_api, ApiTypes). A single expression returns its value; otherwise assign to result.
stdout is captured. Coordinates: mm, Y up. Example: pattern_api.GetPatternCount()
Inputs: code (required), timeout_seconds.
clo_statusA
Check whether CLO is running and the in-CLO bridge is reachable. Returns instructions when it is not.
Inputs: no named parameters.
clo_stop_bridgeA
Stop the bridge loop inside CLO (frees the Python editor; CLO keeps running).
Inputs: no named parameters. Returns: result
clo_ui_actionA
One CLO-only UI action followed by fresh state. action: press, set_value, ax_action (value must be an exposed action), click, right_click, double_click, drag, key, text, scroll (y is vertical wheel delta). Use observed element IDs or SCREEN coordinates from screenshot; key uses macOS virtual keycodes. modifiers: command,shift,option,control. Requires current snapshot token; state is consumed by an action. Never guess coordinates or perform blind action sequences.
Inputs: action (required), snapshot (required), x, y, +6 more.
clo_ui_screenshotA
Capture CLO's window as an image, including UI-only tools and dialogs; independent of API snapshots. Requires Screen Recording. Coordinates in clo_ui_state are screen points, not image pixels.
Inputs: no named parameters.
clo_ui_stateB
Inspect CLO accessibility hierarchy, menus, dialogs, values and supported actions. Returns a snapshot token; use it for the next UI action. No bridge needed. Requires macos extra and Accessibility permission.
Inputs: max_depth, max_nodes.
fabric_applyC
Add a fabric (keyword like 'satin', 'chiffon', 'denim', 'jersey'..., a library file name, or a .zfab path) and assign it to the given pieces (default: all). Optional colour ('#hex' or a colour name) and base texture image.
Inputs: fabric (required), color, patterns, texture_image.
fabric_libraryA
List .zfab fabrics available in the CLO asset library (optionally filtered by substring).
Inputs: filter.
fabric_listC
Fabrics currently in the project's object browser.
Inputs: no named parameters.
fabric_set_colorB
Set the base colour of a fabric already in the project ('#hex' or colour name).
Inputs: color (required), fabric_index (required).
fabric_set_textureC
Apply an image as a fabric's base colour texture (or normal/roughness/opacity map).
Inputs: image_path (required), fabric_index (required), map.
garment_buildD
Inputs: spec (required), views, snapshots, simulate_steps, +1 more.
garment_last_specB
The normalized spec and plan summary of the last garment built in this session.
Inputs: no named parameters.
garment_plan_previewD
Inputs: spec (required), use_scene_measurements.
garment_rebuildB
Re-draft the last built garment with modified spec fields (e.g. {"length": "midi"}, {"neckline": "v", "sleeve": "long"}, {"color": "navy"}, {"fit": "loose"}). Replaces the pieces in CLO and re-simulates.
Inputs: changes (required), snapshots, simulate_steps.
pattern_createB
Create a pattern piece from outline points [[x, y, type], ...] in mm (Y up). type 0 = corner (default), 2 = spline curve point, 3 = bezier control point. Lines are numbered by corner order (line i joins corner i to i+1). Optionally place it on an arrangement point (see arrangement_points).
Inputs: points (required), name, arrangement.
pattern_deleteC
Delete pieces by name or index.
Inputs: patterns (required).
pattern_edit_pointsA
Move outline points of a piece. moves: [{"point": i, "x": .., "y": ..}] absolute or [{"point": i, "dx": .., "dy": ..}] relative (mm, 2D pattern space). Use pattern_info to see point indices/positions. Only corner points are indexed; curve (spline) points on an edge stay where they are, so moving corners of a curved hem distorts it. For built garments prefer garment_rebuild({"length": ...}); use this for straight-edged pieces or small tweaks, then simulate.
Inputs: moves (required), pattern (required).
pattern_infoA
Full information about one piece (by name or index): lines, points (2D mm), arrangement, fabric, seams.
Inputs: pattern (required).
pattern_listA
List pattern pieces (index, name, arrangement, fabric, bbox). detail=True adds each outline line with its length/location (line indices are what sew() uses) and the seam groups per piece.
Inputs: detail.
pattern_opsB
Piece operations. op: rename{name}, move_2d{x,y|dx,dy}, flip{horizontal,each}, copy{dx,dy}, symmetry{with_sewing}, unfold{line,half_symmetry}, layer{layer}, particle_distance{mm}, freeze{on}, hide{on}, strengthen{on}, elastic{line,on,total_length,strength}, shirring{line,on}, delete_line{line}, delete_point{point}.
Inputs: op (required), pattern (required), args.
pattern_set_arrangementC
Place a piece on an avatar arrangement point (e.g. Body_Front_Center_3, Leg_Skirt_Back, Arm_Outside_2_L).
Inputs: point (required), pattern (required).
scene_clearA
Delete all pattern pieces (keep_avatar=True) or start a fresh project (keep_avatar=False).
Inputs: keep_avatar.
scene_exportB
Export the garment: .obj, .fbx, .glb, .gltf, .dxf (patterns), .json (CLO pattern JSON), .zprj, .zpac.
Inputs: path (required), colorways, include_avatar.
scene_infoB
Current CLO scene: project, avatars, pattern pieces (with arrangement point and fabric), fabrics, colorways, seams.
Inputs: no named parameters.
scene_openA
Open a file in CLO: .zprj (project), .zpac (garment), .avt (avatar), .dxf (patterns), pattern .json, .obj/.fbx. mode 'replace' or 'append'.
Inputs: path (required), mode.
scene_saveC
Save the project (.zprj) or garment (.zpac) to a path.
Inputs: path (required), thumbnail.
seams_listA
List sewing groups and the pieces involved.
Inputs: no named parameters.
sewA
Sew line_a of pattern_a to line_b of pattern_b (segment sewing). Directions follow each line's point order; when the two lines run in opposite physical directions set dir_b=False (e.g. front right side <-> back left side with clockwise outlines). Check the result with simulate + snapshot; there is no API to remove a seam, so save a checkpoint first.
Inputs: line_a (required), line_b (required), pattern_a (required), pattern_b (required), +2 more.
simulateA
Run the cloth simulation for N steps (about 30 steps per simulated second). quality: 0 normal, 1 stable, 2 accurate, 3 GPU-fast. particle_distance in mm (smaller = finer, slower; 20 default, 10 for final quality).
Inputs: steps, quality, particle_distance.
simulation_resetA
Reset the garment to its arrangement positions (undo the simulation drape).
Inputs: no named parameters.
snapshotA
Capture the 3D window from one or more views and return the images. views: front, back, left, right, 3/4-right, 3/4-left, top. Default: front and 3/4-right.
Inputs: label, views.
snapshot_2dB
Capture the 2D pattern window (pattern pieces layout).
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 48 tools
Most tools have clear resource/action separation (pattern_, snapshot_, avatar_, scene_, checkpoint_), but several overlapping pairs exist: clo_run_python vs clo_api_search vs clo_api_doc (all about understanding/executing CLO API), clo_status/launch/stop_bridge are distinct but 'garment_plan_preview/build/re_build' have empty descriptions, and garment_rebuild's purpose overlaps conceptually with pattern_edit_points/pattern_ops for modifying garments.
Mostly consistent 'verb_noun' snake_case (pattern_create, scene_open, avatar_list), but there are deviations: some use bare nouns (arrangement_points, scene_info, snapshot), some prefix with 'clo_' while others don't, and 'garment_plan_preview'/'garment_build' sit awkwardly next to 'clo_run_python' and 'sew'.
48 tools is heavy for an MCP server. While the domain (3D garment simulation) is broadath, the count approaches 50, which burdens agent tool-selection. Several tool families (clo_api_*, checkpoint_*, fabric_*, garment_*) could be consolidated or trimmed.
Core lifecycle is covered: scene management, pattern creation/editing, simulation, checkpoints, garment rebuilds, and avatar handling. However, notable gaps exist: no tool to delete a seam or unsew pieces, no fabric creation/management beyond listing and assignment, no animation/pose control for avatars, and garment_plan_preview/build appear to exist but have empty descriptions, leaving their capabilities unclear.
Maintenance
Related MCP Connectors
AI fashion design — product photos, videos, tech packs, colorways & fabric sims.
Build, edit and publish live 3D, AR and game scenes in ARClip from your AI assistant.
Parametric 3D CAD for AI agents: build print-ready parts, check them, export STL, 3MF or STEP.
Create and edit PlayableMaker playable ads from chat and download them as projects.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to control CLO3D for pattern creation, fabric swapping, simulation, and model export via natural language commands.50MIT
- AlicenseBqualityDmaintenanceEnables AI-assisted garment design by letting Claude (or any MCP host) drive CLO3D — import projects, dress avatars, assign fabrics, simulate cloth, render, and export, all from a chat.145MIT
- AlicenseBqualityCmaintenanceConnects MCP-compatible AI agents to a local 3D garment design application through its Python API, enabling scene inspection, pattern and sewing operations, fabric/material management, simulation, mesh measurement, checkpoints, import/export, documentation search, and raw Python execution.42MIT
- AlicenseBqualityBmaintenanceEnables controlling CLO3D from any MCP client to inspect projects, create and edit patterns, manage fabrics and colorways, run simulations, and export models through chat.1042MIT