Skip to main content
Glama
clo3d-mcp

clo3d-mcp

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

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 clo_run_python

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.py

The 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_status and 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 project

The 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 build

The 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.

Contributing · Security · MIT license · Third-party notices

Available Tools

48 tools
arrangement_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_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

    C2.6/5.0

    Scored across 48 tools

    Disambiguation3/5

    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.

    Naming Consistency3/5

    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'.

    Tool Count2/5

    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.

    Completeness3/5

    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

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables 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.
      14
      5
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Connects 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.
      42
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables controlling CLO3D from any MCP client to inspect projects, create and edit patterns, manage fabrics and colorways, run simulations, and export models through chat.
      104
      2
      MIT