vdsl-mcp

MCP server for VDSL — AI-native image generation platform.

RunPod GPU provisioning, ComfyUI orchestration, and model management — all accessible as MCP tools.

Features

• RunPod Pod Management — Create, start, stop, delete GPU pods. Auto-setup with ComfyUI template.
• ComfyUI Integration — Connect, query models, submit workflows, poll results, download images.
• Model Download — HuggingFace (hf:), CivitAI (cv:) with automatic token injection, or direct URLs.
• B2 Cold Storage — List, pull, and push models between pods and Backblaze B2 via rclone.
• Project Sync — $VDSL_WORK_DIR/projects/<name>/ (notes, refs, sweeps, final, etc.) is synced to B2 at vdsl/projects/ independently from the output location; no pod connection required.
• Image Batch Download — Download all output images from ComfyUI history to a local directory.
• Batch Generation — Submit multiple workflows, poll all jobs, download all outputs.
• VDSL Script Execution — Run Lua scripts that compile into ComfyUI workflows.
• RunPod CLI Passthrough — Execute any runpod-cli command with auto API key injection.
• ComfyUI API — Generic REST API access with automatic authentication.

MCP Tools

Installation

# 1. Install the MCP server binary
cargo install vdsl-mcp

# 2. Clone VDSL runtime (Lua DSL modules — required for vdsl_run / vdsl_catalogs)
git clone https://github.com/ynishi/vdsl.git ~/vdsl

The binary alone is sufficient for direct ComfyUI workflow submission (vdsl_generate). To use the Lua DSL (vdsl_run, vdsl_catalogs), the VDSL runtime repository is required — it provides the lua/ directory containing catalog definitions, compilers, and pipeline logic.

Configuration

Environment Variables

.env file auto-loading

vdsl-mcp loads variables from .env files at startup so that secrets do not need to be embedded in .mcp.json. Search order (first writer wins; OS env is always preserved):

1. OS environment (already exported in the shell / parent process)
2. $VDSL_ENV_FILE if set
3. ~/.config/vdsl-mcp/.env
4. $CWD/.env

Recommended layout: keep the .mcp.json env block free of secrets (only VDSL_WORK_DIR and similar non-secret paths) and place tokens in ~/.config/vdsl-mcp/.env with chmod 600. Values containing literal $ (e.g. bcrypt hashes) must be single-quoted in the .env file because dotenvy performs $VAR expansion in unquoted values.

MCP Client Configuration

Minimal (local ComfyUI only)

{
  "mcpServers": {
    "vdsl": {
      "command": "vdsl-mcp"
    }
  }
}

Then connect with vdsl_connect(url="http://localhost:8188").

Full (RunPod + B2 storage)

{
  "mcpServers": {
    "vdsl": {
      "command": "vdsl-mcp",
      "env": {
        "VDSL_RUNPOD_API_KEY": "rpa_...",
        "VDSL_SSH_KEY": "~/.ssh/id_ed25519",
        "VDSL_COMFYUI_TOKEN": "your-comfyui-token",
        "VDSL_CIVITAI_TOKEN": "your-civitai-token",
        "VDSL_B2_KEY_ID": "your-b2-key-id",
        "VDSL_B2_KEY": "your-b2-key",
        "VDSL_B2_BUCKET": "your-bucket-name"
      }
    }
  }
}

Usage

Quick Start (local ComfyUI)

1. vdsl_connect(url="http://localhost:8188") — Connect to ComfyUI
2. vdsl_models — List available checkpoints and LoRAs
3. vdsl_generate(workflow) — Generate images from a workflow JSON

VDSL Lua DSL

Compile human-readable Lua scripts into ComfyUI workflows:

1. vdsl_catalogs — Browse available catalog entries (camera angles, lighting, figures, etc.)
2. vdsl_run(script_file="~/vdsl/examples/mlua_verify_p1.lua") — Compile + generate
3. vdsl_run(code="...", working_dir="~/vdsl") — Run inline Lua code

The working_dir must point to the cloned VDSL repository (contains lua/ for module resolution). When script_file is used, working_dir is auto-detected by walking up from the script's parent directory.

Infrastructure (RunPod)

1. vdsl_pod_list — List pods with GPU info
2. vdsl_pod_setup — Find or create a GPU pod, wait until ready
3. vdsl_exec(command="nvidia-smi") — Run commands on the pod via SSH
4. vdsl_task_run(command="...") — Start long-running background jobs
5. vdsl_download(source="hf:...", target="loras") — Download models to the pod

SSH Tunnel (bypass Cloudflare proxy)

Open a stable local-port-forward tunnel to a pod to avoid Cloudflare proxy instability:

1. vdsl_tunnel_open(pod_id="...", service="comfyui", remote_port=8188) — Open tunnel; returns local port (e.g. 7100) or falls back silently to the Cloudflare proxy URL if SSH info is unavailable
2. vdsl_tunnel_list — Inspect active tunnels (route: ssh-tunnel | cloudflare-proxy)
3. vdsl_connect(url="http://127.0.0.1:7100") — Connect via the tunnel
4. vdsl_tunnel_close(pod_id="...") — Close the tunnel when done

vdsl_pod_list reflects the active route for each endpoint in its endpoints[] field so you can verify routing at a glance.

Cold Storage (B2)

1. vdsl_storage_list — List files in B2
2. vdsl_storage_pull(source="models/loras/my.safetensors", target="loras") — Restore from B2
3. vdsl_storage_archive(source_target="loras", filename="old.safetensors") — Archive to B2 (push → verify → delete)

Model Sources

hf:user/repo/model.safetensors        # HuggingFace
cv:1595775                             # CivitAI (token auto-injected)
https://example.com/model.safetensors  # Direct URL
user/repo/model.safetensors            # Bare path (defaults to HuggingFace)

Related

• VDSL — VDSL core (Lua DSL for visual generation)

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.