Content
# ltx-trainer-mcp
MCP server for the official LTX-2.3 video model trainer — LoRA, IC-LoRA,
and full fine-tuning from any AI agent.
Wraps the official [LTX-2 trainer](https://github.com/Lightricks/LTX-2/tree/main/packages/ltx-trainer)
by Lightricks. All operations shell out to
`uv run python packages/ltx-trainer/scripts/...` inside the LTX-2
monorepo — this server never imports trainer internals.
## Companion servers
This is one of three MCP servers designed to work together for
agent-driven video training workflows:
- [klippbok-mcp](https://github.com/hoodtronik/klippbok-mcp) — dataset curation (scene selection, captioning)
- [musubi-mcp](https://github.com/hoodtronik/musubi-mcp) — Wan / FLUX / Z-Image training
- **ltx-trainer-mcp** (this repo) — LTX-2 / LTX-2.3 training
Together: curate a dataset in Klippbok, train Wan / FLUX / Z-Image
through Musubi, train LTX-2.3 video through this server — all from the
same agent conversation.
## Platform support
| Platform | Server itself | Dataset prep / training |
|----------|---------------|-------------------------|
| Linux (CUDA) | ✅ | ✅ |
| Windows (WSL2) | ✅ | ✅ |
| Windows (native) | ✅ | ❌ (triton + bitsandbytes are Linux-only) |
| macOS | ✅ | ❌ |
The MCP server installs and runs on any platform — `ltx_check_installation`
will flag the Linux-only requirement so agents can warn the user up
front. Config authoring (`ltx_create_config`, `ltx_read_config`,
`ltx_update_config`) is fully functional everywhere.
## Quick start
```bash
git clone https://github.com/hoodtronik/ltx-trainer-mcp
cd ltx-trainer-mcp
# Clone LTX-2 somewhere (sibling dir is conventional)
git clone https://github.com/Lightricks/LTX-2 ../LTX-2
# Install from the repo
uv venv .venv
uv pip install --python .venv/Scripts/python.exe -e .
# Smoke test
LTX_TRAINER_DIR=../LTX-2 .venv/Scripts/python.exe -m ltx_trainer_mcp.server
# (the process blocks waiting for stdio MCP protocol input — this is expected)
```
## Client configuration
### Claude Desktop
`claude_desktop_config.json`:
```json
{
"mcpServers": {
"ltx-trainer": {
"command": "uv",
"args": ["run", "--directory", "/abs/path/to/ltx-trainer-mcp", "ltx-trainer-mcp"],
"env": {
"LTX_TRAINER_DIR": "/abs/path/to/LTX-2"
}
}
}
}
```
### The full three-server stack
```json
{
"mcpServers": {
"klippbok": {
"command": "uv",
"args": ["run", "--directory", "/abs/path/to/klippbok-mcp", "klippbok-mcp"],
"env": {
"KLIPPBOK_PYTHON": "/abs/path/to/klippbok-venv/bin/python",
"GEMINI_API_KEY": "..."
}
},
"musubi": {
"command": "uv",
"args": ["run", "--directory", "/abs/path/to/musubi-mcp", "musubi-mcp"],
"env": {
"MUSUBI_TUNER_DIR": "/abs/path/to/musubi-tuner",
"MUSUBI_PYTHON": "/abs/path/to/musubi-venv/bin/python"
}
},
"ltx-trainer": {
"command": "uv",
"args": ["run", "--directory", "/abs/path/to/ltx-trainer-mcp", "ltx-trainer-mcp"],
"env": { "LTX_TRAINER_DIR": "/abs/path/to/LTX-2" }
}
}
}
```
## Tools
**Dataset prep**
| Tool | Description |
|------|-------------|
| `ltx_split_scenes` | Split long videos into per-scene clips |
| `ltx_caption_videos` | Auto-caption video clips ([VISUAL]/[SPEECH]/[SOUNDS]/[TEXT]) |
| `ltx_process_dataset` | Compute video latents + text embeddings (heavy preprocess step) |
**Config authoring — the primary customization interface**
| Tool | Description |
|------|-------------|
| `ltx_list_configs` | Enumerate built-in templates |
| `ltx_create_config` | Generate a training YAML from template + overrides |
| `ltx_read_config` | Load an existing YAML as structured data |
| `ltx_update_config` | Modify specific fields in-place and return a diff |
**Training**
| Tool | Description |
|------|-------------|
| `ltx_train` | Launch training (24h timeout); single-GPU or `accelerate launch` with DDP/FSDP |
| `ltx_list_checkpoints` | Enumerate `.safetensors` files under an output dir, newest first |
**Inference**
| Tool | Description |
|------|-------------|
| `ltx_generate` | Run one of 8 `ltx-pipelines` pipelines (ti2vid/distilled/ic_lora/a2vid/retake/…) |
**System**
| Tool | Description |
|------|-------------|
| `ltx_check_installation` | Report on OS / GPU / uv / template availability |
## Resources
| URI | Content |
|-----|---------|
| `ltx://docs/quick-start` | Upstream quick-start guide |
| `ltx://docs/dataset-preparation` | Scene split, captioning, process_dataset usage |
| `ltx://docs/training-modes` | LoRA / audio-video / IC-LoRA / full fine-tuning |
| `ltx://docs/configuration-reference` | Every YAML config key the trainer accepts |
| `ltx://docs/troubleshooting` | Common failure modes and fixes |
| `knowledge://index` | Table of contents for the community LoRA training knowledge base |
| `knowledge://ltx23_training` | Curated LTX-2.3 hyperparameters, resolution rules, INT8 vs full config |
| `knowledge://dataset_quality` | Captioning / clip-count / resolution guidance |
| `knowledge://hardware_profiles` | VRAM requirements + block-swap tuning by GPU tier |
| `knowledge://common_failures` | Diagnostic lookup for loss misbehaviour mid-run |
| `knowledge://<other>` | Cross-arch training docs (`wan22_training`, `flux2_klein_training`, `hunyuanvideo_training`, …) |
`ltx://docs/*` reads the corresponding markdown file from the LTX-2
monorepo at request time. `knowledge://*` serves curated community
training notes — bundled with the package and mirrored across
`klippbok-mcp`, `musubi-mcp`, and this server so agents get the same
reference regardless of which server they call. Files flagged
**`INSUFFICIENT DATA`** are exposed verbatim so the orchestration agent
sees the gap and asks the user rather than guessing. Loading priority
for `knowledge://*`: `$KNOWLEDGE_BASE_DIR` env var (for live-sync with
a central knowledge base), else the bundled copy.
## Prompts
| Prompt | Description |
|--------|-------------|
| `plan_ltx_training` | Draft an end-to-end plan from goal + hardware + source + mode |
| `diagnose_ltx_issue` | Classify a trainer failure from log output + optional config path |
## Environment variables
| Variable | Required? | Default | Purpose |
|----------|-----------|---------|---------|
| `LTX_TRAINER_DIR` | yes | — | Absolute path to the LTX-2 monorepo |
| `LTX_UV_PATH` | no | `uv` | Override if `uv` isn't on PATH |
| `KNOWLEDGE_BASE_DIR` | no | bundled | Override source folder for `knowledge://*` resources. Live-syncs with a central LoRA training knowledge base; falls back to the bundled copy when unset or invalid. |
## License
Apache 2.0. Wraps the Apache 2.0-licensed
[LTX-2 trainer](https://github.com/Lightricks/LTX-2).
