chutes-media-mcp

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

Independent community project. Not officially affiliated with or endorsed by Chutes.

Quick start

Requires Node.js 20.3+ and a Chutes API key. Add the server to Claude Code:

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

Then ask your agent naturally:

Generate a cinematic hero image of a misty mountain range and save it in this project.

The agent discovers a suitable model, reads its live input schema, validates the request, and saves the result under assets/chutes/<kind>/. For Cursor, Cline, Windsurf, OpenCode and Claude Desktop, see Use as an MCP server.

Why chutes-media-mcp?

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) documenting the describe→generate workflow (auto-loaded by Claude Code; usable as reference by any agent).

Both frontends are thin adapters over one shared, transport-agnostic core.

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.
• 🧾 Provenance + guardrails: writes a sidecar (model, params, schema hash) next to each asset, rejects unknown params, and verifies the returned media type matches what you asked for.
• 🔁 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.

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.3 for the published MCP server and CLI
• Use a supported LTS release (Node.js 22 or 24) for production. Node.js 20 compatibility is retained for the current major release, but Node.js 20 itself is end-of-life.
• Contributors using the locked quality toolchain need Node.js ^20.19.0, ≥ 22.13.0, or ≥ 24
• A Chutes API key (CHUTES_API_KEY). Create one in your Chutes account.

Installation options

An MCP server isn't "installed" like an app — it's registered as a command in your MCP client's config (see Use as an MCP server). Pick whichever way of providing that command suits you:

1. npx from npm — recommended (no install):

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

2. Global install:

npm install -g chutes-media-mcp
# then `chutes-media-mcp` (server) and `chutes-media` (CLI) are on your PATH

3. Directly from GitHub (no npm needed): builds on install via the prepare script.

npx -y github:TheStreamCode/chutes-media-mcp

4. From source (for development):

git clone https://github.com/TheStreamCode/chutes-media-mcp
cd chutes-media-mcp && npm ci && npm run build
# then point your client at: node /abs/path/dist/mcp/server.js

The package ships two bins: chutes-media-mcp (the MCP server) and chutes-media (the CLI).

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. Output traversal and symlink escapes are rejected. Existing files are not replaced unless overwrite is explicitly enabled.

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 / OpenCode / Claude Desktop (generic mcpServers config):

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

To run without npm, replace the args with ["-y", "github:TheStreamCode/chutes-media-mcp"].

Tools