chutes-media-mcp

Generate image, video, music and speech through Chutes from inside any coding agent — Claude Code, Cursor, Cline, Windsurf, Codex, Claude Desktop — and have the generated asset saved straight into the project you're working on.

It ships as:

• an MCP server (chutes-media-mcp, stdio) — the primary, universal interface,

• a thin CLI (chutes-media) — a fallback for shells and agents without MCP support, and

• an optional Agent Skill (skill/chutes-media) that teaches Claude-family agents the workflow.

Both frontends are thin adapters over one shared, transport-agnostic core, so they behave identically.

Not officially affiliated with or endorsed by Chutes. "Chutes" belongs to its respective owners; this is an independent, open-source community tool.

Features

• 🎨 Four media kinds: image, video, music, speech — plus image editing (img2img / inpaint) when a model exposes an edit cord.

• 🔎 describe → generate workflow: the live model schema is fetched and handed to the agent; payloads are never hardcoded.

• 💾 Saves assets into your project (default ./assets/chutes/<kind>/) and returns the path.

• ✅ Validates the payload against the live schema before spending a GPU call.

• 🔁 Automatic cold-start retry with backoff for models scaled to zero.

• 📡 Progress updates during long video/music jobs (MCP progress notifications / CLI stderr).

• 🧩 Works everywhere: MCP server or CLI, same behavior.

Related MCP server: Pollinations Multimodal MCP Server

How it works: describe → generate

Chutes models differ wildly (FLUX vs Qwen-Image vs Wan vs LTX vs ACE-Step vs a TTS model), so payloads are never hardcoded. The flow is always:

1. list_media_models — discover a model for the kind you want.

2. describe_media_model — fetch the model's live cords and input schema.

3. generate_media — submit the payload you composed; the asset is saved into the workspace.

The server owns all the plumbing: auth, cold-start warmup + retry, blocking invocation with progress, downloading, saving, light validation, and best-effort cost reporting.

Requirements

• Node.js ≥ 20

• A Chutes API key (CHUTES_API_KEY). Create one in your Chutes account.

Install

Run it on demand with npx (no install needed):

npx chutes-media-mcp     # MCP server (stdio)
npx chutes-media --help  # CLI

…or install globally:

npm install -g chutes-media-mcp

Configuration

Generated assets are saved to ./assets/chutes/<kind>/ by default, relative to wherever the agent is running — so they land inside the project being worked on.

Use as an MCP server

Claude Code:

claude mcp add chutes-media --env CHUTES_API_KEY=cpk_your_key -- npx -y chutes-media-mcp

Cursor / Cline / Windsurf / Claude Desktop (generic mcpServers config):

{
  "mcpServers": {
    "chutes-media": {
      "command": "npx",
      "args": ["-y", "chutes-media-mcp"],
      "env": { "CHUTES_API_KEY": "cpk_your_key" }
    }
  }
}

Tools

• list_media_models — { kind?, query?, limit? } → matching models.

• describe_media_model — { model } → every cord with required fields, types, defaults, a minimal example payload, and a top-level supportsEditing. Call this before generating.

• generate_media — { model, kind, params, cord?, output_dir?, filename?, timeout_ms? } → runs the generation and returns { path, kind, model, cord, bytes, contentType, cost?, durationMs }. params is what you composed from the described schema.

Example agent workflow

"Generate a hero image of a misty mountain range and drop it into the landing page."

The agent calls describe_media_model on an image model, composes { prompt: "misty mountain range at dawn, cinematic", width: 1024, height: 1024 }, calls generate_media, gets back ./assets/chutes/image/<model>-<timestamp>.png, and references that path in index.html.

Use as a CLI

export CHUTES_API_KEY="cpk_your_key"          # PowerShell: $env:CHUTES_API_KEY = "cpk_..."

# Discover models
chutes-media list --kind image
chutes-media list --query flux

# Inspect a model's schema
chutes-media describe owner/model-slug

# Generate (inline JSON, @file, or a path to a .json file for --params)
chutes-media generate --kind image --model owner/model-slug \
  --params '{"prompt":"a red bicycle on a cobblestone street"}'

Progress is printed to stderr; the JSON result (including the saved path) is printed to stdout, so agents can parse it.

Image editing (img2img / inpaint)

Chutes has no platform-wide edit endpoint. Editing exists only when a model publishes an edit cord (e.g. img2img, inpaint) or is a dedicated edit model. describe_media_model reports supportsEditing and lists those cords. To use one, reference a workspace file in params (a single field like image, or an array like image_b64s) — the server reads the file and base64-encodes it:

chutes-media generate --kind image --model owner/edit-capable --cord img2img \
  --params '{"prompt":"make it snowy","image":"assets/chutes/image/scene.jpg","strength":0.6}'

When a model has no edit cord, only generation is available.

Agent Skill (optional)

skill/chutes-media is an Agent Skill that teaches Claude-family agents the describe→generate discipline, payload composition, editing, and cold-start handling. Install it by copying the folder into your skills directory:

cp -r skill/chutes-media ~/.claude/skills/chutes-media          # user-level
# or, per project:
cp -r skill/chutes-media .claude/skills/chutes-media

Non-Claude agents don't need it — they just call the tools/CLI directly.

Cost

Chutes prices by compute units. When a model exposes the cost via a response header it is returned as cost; otherwise cost is omitted. Check the Chutes pricing for per-model rates.

💡 Many public models scale to zero and may return 503 no-instances until they warm up. The server retries automatically; if a model stays cold, pick another of the same kind.

Development

See CONTRIBUTING.md for setup, the build/test commands, and the Windows #-path caveat. Quick version:

npm install
npm run typecheck
npm run test
npm run build

Security

Never commit your API key. See SECURITY.md for how the key is handled and how to report vulnerabilities.

Author

Built by Michael Gasperini — founder of Mikesoft, building small, focused, privacy-aware developer tools.

License

MIT © Michael Gasperini (Mikesoft)