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.
| Live model contract | Safer project I/O | Project-native output | One shared core |
|---|
| Reads each model's current schema instead of hardcoding payloads. | Contains file access to the workspace and protects existing assets by default. | Saves generated media and optional provenance directly beside your code. | MCP and CLI expose the same discovery, validation and generation behavior. |
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:
list_media_models — discover a model for the kind you want.describe_media_model — fetch the model's live cords and input schema.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
npx -p chutes-media-mcp chutes-media --help
2. Global install:
npm install -g chutes-media-mcp
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
The package ships two bins: chutes-media-mcp (the MCP server) and chutes-media (the CLI).
Configuration
| Variable | Required | Default | Purpose |
|---|
CHUTES_API_KEY | ✅ | — | Your Chutes API key. Read from the environment; never written to disk. |
CHUTES_AUTH_SCHEME | | raw | How the key is sent in Authorization: raw (the key as-is) or bearer (prefixed Bearer ). On a 401, try flipping this. |
CHUTES_API_BASE_URL | | https://api.chutes.ai | Management API base URL. HTTPS is required except for loopback development; custom endpoints receive no Chutes API key. |
CHUTES_OUTPUT_DIR | | assets/chutes | Output directory inside the agent's CWD. A <kind>/ subfolder is appended. |
CHUTES_WARMUP | | true | Warm models up before invoking. Set false to skip. |
CHUTES_COLD_START_RETRIES | | 4 | Retries when a cold model returns 503 no-instances (0 disables). |
CHUTES_COLD_START_BACKOFF_MS | | 8000 | Base backoff between cold-start retries (grows per attempt). |
CHUTES_MAX_ASSET_MB | | 512 | Maximum response or local input-asset size accepted in memory (max 4096). |
CHUTES_PROGRESS_INTERVAL_MS | | 5000 | How often progress heartbeats are emitted while a call blocks. |
CHUTES_ALLOW_UNKNOWN_PARAMS | | false | When true, allow params not in the model schema. Default rejects them so a renamed/unknown field fails loudly. |
CHUTES_PROVENANCE | | true | Write a <asset>.json provenance sidecar (model, cord, params, schema hash). Set false to disable. |
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"].
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?, overwrite? } →
runs the generation and returns
{ path, kind, model, cord, bytes, contentType, cost?, durationMs, schemaHash?, provenancePath? }.
params is what you composed from the described schema. schemaHash pins the exact cord schema the
payload was validated against; provenancePath points at the sidecar (omitted when
CHUTES_PROVENANCE=false).
Each tool publishes an output schema and returns the same JSON object both as text and as MCP
structuredContent, so clients can consume typed results without parsing the text representation.
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"
chutes-media list --kind image
chutes-media list --query flux
chutes-media describe owner/model-slug
chutes-media generate --kind image --model owner/model-slug \
--params '{"prompt":"a red bicycle on a cobblestone street"}'
chutes-media generate --kind image --model owner/model-slug --filename hero.jpg --overwrite \
--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)
The MCP server already ships instructions (the describe→generate workflow), so any client receives
guidance on connect — no skill required.
For Claude Code you can additionally install the bundled Agent Skill
(skill/chutes-media) for richer, auto-loaded guidance:
npx -p chutes-media-mcp chutes-media install-skill
npx -p chutes-media-mcp chutes-media install-skill --project
(Or copy the folder into your skills directory manually.) Agents without skill auto-loading don't
need it — the tool descriptions and server instructions already guide them.
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:
Security
Never commit your API key. Credential-bearing requests are limited to HTTPS Chutes hosts, remote
asset URLs are screened against private-network destinations, and file access is contained to the
workspace. Query strings and fragments are removed from network-error messages so signed asset URLs
are not copied into logs. See SECURITY.md for details and vulnerability reporting.
Migrating from 1.x
Version 2.0 makes the safety boundaries enforceable instead of best-effort:
- Existing named assets are preserved unless
overwrite / --overwrite is explicitly set.
- Input and output paths must resolve inside the current workspace; symlink and junction escapes are
rejected.
- Custom management API URLs require HTTPS, except loopback URLs used for local development. The
Chutes API key is never attached to custom or loopback management endpoints.
- Management and invocation credentials are sent only to HTTPS Chutes hosts, and asset downloads
must resolve to public HTTPS destinations.
- Responses and local input assets are capped by
CHUTES_MAX_ASSET_MB (512 MiB by default).
If an existing automation intentionally replaces a file, add the explicit overwrite option after
confirming the target path.
Support
Author
Built by Michael Gasperini — founder of Mikesoft,
building small, focused, privacy-aware developer tools.
If this project is useful to you, consider sponsoring its development.
License
Project-owned code, documentation, and other project-created materials are
licensed under the MIT License, except for the third-party rights
below.
Third-party notices and provider terms
This independent project is not affiliated with, sponsored by, or endorsed by
Chutes Global Corp. The Chutes name, logo, platform, services, branding, and
related marks are the property of Chutes Global Corp or their respective
owners. The MIT License and this project grant no rights to use them.
assets/chutes-media-mcp.png is the only
project image in this repository that incorporates Chutes logo/marks. It is one
of exactly three user-created Chutes-logo image compositions across the Chutes
projects; the embedded Chutes logo/marks remain the property of their owner and
are not licensed under MIT.
The MIT License does not grant rights in Chutes services or in third-party
models, model content, or generated outputs. Their use is subject to applicable
provider terms and model licenses. Review Chutes' official Terms of
Service and Privacy Policy.
See NOTICE for the packaged notice.