{
  "markdown": "# chutes-media-mcp\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)\n[![Node >= 20.3](https://img.shields.io/badge/node-%3E%3D20.3-brightgreen.svg)](https://nodejs.org)\n[![npm](https://img.shields.io/npm/v/chutes-media-mcp.svg)](https://www.npmjs.com/package/chutes-media-mcp)\n[![CI](https://github.com/TheStreamCode/chutes-media-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/TheStreamCode/chutes-media-mcp/actions/workflows/ci.yml)\n\nGenerate **image, video, music and speech** through [Chutes](https://chutes.ai) from inside any\ncoding agent — Claude Code, Cursor, Cline, Windsurf, Codex, OpenCode, Claude Desktop — and save the\ngenerated asset straight into the project you're working on.\n\n> **Independent community project.** Not officially affiliated with or endorsed by Chutes.\n\n## Quick start\n\nRequires **Node.js 20.3+** and a [Chutes API key](https://chutes.ai). Add the server to Claude Code:\n\n```bash\nclaude mcp add chutes-media --env CHUTES_API_KEY=cpk_your_key -- npx -y chutes-media-mcp\n```\n\nThen ask your agent naturally:\n\n> Generate a cinematic hero image of a misty mountain range and save it in this project.\n\nThe agent discovers a suitable model, reads its live input schema, validates the request, and saves\nthe result under `assets/chutes/<kind>/`. For Cursor, Cline, Windsurf, OpenCode and Claude Desktop,\nsee [Use as an MCP server](#use-as-an-mcp-server).\n\n<p align=\"center\">\n  <img src=\"https://raw.githubusercontent.com/TheStreamCode/chutes-media-mcp/main/assets/chutes-media-mcp.png\" alt=\"chutes-media-mcp\" width=\"720\">\n</p>\n\n## Why chutes-media-mcp?\n\n| Live model contract                                               | Safer project I/O                                                              | Project-native output                                                    | One shared core                                                            |\n| ----------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------ | -------------------------------------------------------------------------- |\n| 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. |\n\nIt ships as:\n\n- an **MCP server** (`chutes-media-mcp`, stdio) — the primary, universal interface,\n- a thin **CLI** (`chutes-media`) — a fallback for shells and agents without MCP support, and\n- an optional **Agent Skill** ([`skill/chutes-media`](./skill/chutes-media)) documenting the\n  describe→generate workflow (auto-loaded by Claude Code; usable as reference by any agent).\n\nBoth frontends are thin adapters over one shared, transport-agnostic core.\n\n---\n\n## Features\n\n- 🎨 Four media kinds: **image, video, music, speech** — plus **image editing** (img2img / inpaint)\n  when a model exposes an edit cord.\n- 🔎 **describe → generate** workflow: the live model schema is fetched and handed to the agent;\n  payloads are never hardcoded.\n- 💾 Saves assets into your project (default `./assets/chutes/<kind>/`) and returns the path.\n- ✅ **Validates** the payload against the live schema before spending a GPU call.\n- 🧾 **Provenance + guardrails**: writes a sidecar (model, params, schema hash) next to each asset,\n  rejects unknown params, and verifies the returned media type matches what you asked for.\n- 🔁 **Automatic cold-start retry** with backoff for models scaled to zero.\n- 📡 Progress updates during long video/music jobs (MCP progress notifications / CLI stderr).\n- 🧩 Works everywhere: MCP server **or** CLI, same behavior.\n\n## How it works: describe → generate\n\nChutes models differ wildly (FLUX vs Qwen-Image vs Wan vs LTX vs ACE-Step vs a TTS model), so\npayloads are **never hardcoded**. The flow is always:\n\n1. **`list_media_models`** — discover a model for the kind you want.\n2. **`describe_media_model`** — fetch the model's live cords and input schema.\n3. **`generate_media`** — submit the payload you composed; the asset is saved into the workspace.\n\nThe server owns all the plumbing: auth, cold-start warmup + retry, blocking invocation with progress,\ndownloading, saving, light validation, and best-effort cost reporting.\n\n---\n\n## Requirements\n\n- **Node.js ≥ 20.3** for the published MCP server and CLI\n- Use a supported LTS release (**Node.js 22 or 24**) for production. Node.js 20 compatibility is\n  retained for the current major release, but Node.js 20 itself is end-of-life.\n- Contributors using the locked quality toolchain need **Node.js ^20.19.0, ≥ 22.13.0, or ≥ 24**\n- A **Chutes API key** (`CHUTES_API_KEY`). Create one in your Chutes account.\n\n## Installation options\n\nAn MCP server isn't \"installed\" like an app — it's registered as a **command** in your MCP client's\nconfig (see [Use as an MCP server](#use-as-an-mcp-server)). Pick whichever way of providing that\ncommand suits you:\n\n**1. `npx` from npm — recommended (no install):**\n\n```bash\nnpx chutes-media-mcp        # MCP server (stdio)\nnpx -p chutes-media-mcp chutes-media --help   # CLI bin\n```\n\n**2. Global install:**\n\n```bash\nnpm install -g chutes-media-mcp\n# then `chutes-media-mcp` (server) and `chutes-media` (CLI) are on your PATH\n```\n\n**3. Directly from GitHub (no npm needed):** builds on install via the `prepare` script.\n\n```bash\nnpx -y github:TheStreamCode/chutes-media-mcp\n```\n\n**4. From source (for development):**\n\n```bash\ngit clone https://github.com/TheStreamCode/chutes-media-mcp\ncd chutes-media-mcp && npm ci && npm run build\n# then point your client at: node /abs/path/dist/mcp/server.js\n```\n\n> The package ships two bins: `chutes-media-mcp` (the MCP server) and `chutes-media` (the CLI).\n\n## Configuration\n\n| Variable                       | Required | Default                 | Purpose                                                                                                                      |\n| ------------------------------ | -------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------- |\n| `CHUTES_API_KEY`               | ✅       | —                       | Your Chutes API key. Read from the environment; never written to disk.                                                       |\n| `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. |\n| `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.      |\n| `CHUTES_OUTPUT_DIR`            |          | `assets/chutes`         | Output directory inside the agent's CWD. A `<kind>/` subfolder is appended.                                                  |\n| `CHUTES_WARMUP`                |          | `true`                  | Warm models up before invoking. Set `false` to skip.                                                                         |\n| `CHUTES_COLD_START_RETRIES`    |          | `4`                     | Retries when a cold model returns `503 no-instances` (`0` disables).                                                         |\n| `CHUTES_COLD_START_BACKOFF_MS` |          | `8000`                  | Base backoff between cold-start retries (grows per attempt).                                                                 |\n| `CHUTES_MAX_ASSET_MB`          |          | `512`                   | Maximum response or local input-asset size accepted in memory (max `4096`).                                                  |\n| `CHUTES_PROGRESS_INTERVAL_MS`  |          | `5000`                  | How often progress heartbeats are emitted while a call blocks.                                                               |\n| `CHUTES_ALLOW_UNKNOWN_PARAMS`  |          | `false`                 | When `true`, allow params not in the model schema. Default rejects them so a renamed/unknown field fails loudly.             |\n| `CHUTES_PROVENANCE`            |          | `true`                  | Write a `<asset>.json` provenance sidecar (model, cord, params, schema hash). Set `false` to disable.                        |\n\nGenerated assets are saved to `./assets/chutes/<kind>/` by default, relative to wherever the agent is\nrunning — so they land inside the project being worked on. Output traversal and symlink escapes are\nrejected. Existing files are not replaced unless `overwrite` is explicitly enabled.\n\n---\n\n## Use as an MCP server\n\n**Claude Code:**\n\n```bash\nclaude mcp add chutes-media --env CHUTES_API_KEY=cpk_your_key -- npx -y chutes-media-mcp\n```\n\n**Cursor / Cline / Windsurf / OpenCode / Claude Desktop** (generic `mcpServers` config):\n\n```json\n{\n  \"mcpServers\": {\n    \"chutes-media\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"chutes-media-mcp\"],\n      \"env\": { \"CHUTES_API_KEY\": \"cpk_your_key\" }\n    }\n  }\n}\n```\n\n> To run without npm, replace the args with `[\"-y\", \"github:TheStreamCode/chutes-media-mcp\"]`.\n\n### Tools\n\n- **`list_media_models`** — `{ kind?, query?, limit? }` → matching models.\n- **`describe_media_model`** — `{ model }` → every cord with required fields, types, defaults, a\n  minimal example payload, and a top-level `supportsEditing`. Call this before generating.\n- **`generate_media`** — `{ model, kind, params, cord?, output_dir?, filename?, timeout_ms?, overwrite? }` →\n  runs the generation and returns\n  `{ path, kind, model, cord, bytes, contentType, cost?, durationMs, schemaHash?, provenancePath? }`.\n  `params` is what you composed from the described schema. `schemaHash` pins the exact cord schema the\n  payload was validated against; `provenancePath` points at the sidecar (omitted when\n  `CHUTES_PROVENANCE=false`).\n\nEach tool publishes an output schema and returns the same JSON object both as text and as MCP\n`structuredContent`, so clients can consume typed results without parsing the text representation.\n\n### Example agent workflow\n\n> \"Generate a hero image of a misty mountain range and drop it into the landing page.\"\n\nThe agent calls `describe_media_model` on an image model, composes\n`{ prompt: \"misty mountain range at dawn, cinematic\", width: 1024, height: 1024 }`, calls\n`generate_media`, gets back `./assets/chutes/image/<model>-<timestamp>.png`, and references that path\nin `index.html`.\n\n---\n\n## Use as a CLI\n\n```bash\nexport CHUTES_API_KEY=\"cpk_your_key\"          # PowerShell: $env:CHUTES_API_KEY = \"cpk_...\"\n\n# Discover models\nchutes-media list --kind image\nchutes-media list --query flux\n\n# Inspect a model's schema\nchutes-media describe owner/model-slug\n\n# Generate (inline JSON, @file, or a path to a .json file for --params)\nchutes-media generate --kind image --model owner/model-slug \\\n  --params '{\"prompt\":\"a red bicycle on a cobblestone street\"}'\n\n# Replacing an existing named asset must be explicit\nchutes-media generate --kind image --model owner/model-slug --filename hero.jpg --overwrite \\\n  --params '{\"prompt\":\"a red bicycle on a cobblestone street\"}'\n```\n\nProgress is printed to **stderr**; the JSON result (including the saved `path`) is printed to\n**stdout**, so agents can parse it.\n\n---\n\n## Image editing (img2img / inpaint)\n\nChutes has **no platform-wide edit endpoint**. Editing exists only when a model publishes an edit\ncord (e.g. `img2img`, `inpaint`) or is a dedicated edit model. `describe_media_model` reports\n`supportsEditing` and lists those cords. To use one, reference a workspace file in `params` (a single\nfield like `image`, or an array like `image_b64s`) — the server reads the file and base64-encodes it:\n\n```bash\nchutes-media generate --kind image --model owner/edit-capable --cord img2img \\\n  --params '{\"prompt\":\"make it snowy\",\"image\":\"assets/chutes/image/scene.jpg\",\"strength\":0.6}'\n```\n\nWhen a model has no edit cord, only generation is available.\n\n---\n\n## Agent Skill (optional)\n\nThe MCP server already ships **instructions** (the describe→generate workflow), so any client receives\nguidance on connect — no skill required.\n\nFor Claude Code you can additionally install the bundled **Agent Skill**\n([`skill/chutes-media`](./skill/chutes-media)) for richer, auto-loaded guidance:\n\n```bash\nnpx -p chutes-media-mcp chutes-media install-skill             # → ~/.claude/skills/chutes-media\nnpx -p chutes-media-mcp chutes-media install-skill --project   # → ./.claude/skills/chutes-media\n```\n\n(Or copy the folder into your skills directory manually.) Agents without skill auto-loading don't\nneed it — the tool descriptions and server instructions already guide them.\n\n---\n\n## Cost\n\nChutes prices by compute units. When a model exposes the cost via a response header it is returned as\n`cost`; otherwise `cost` is omitted. Check the [Chutes pricing](https://chutes.ai) for per-model\nrates.\n\n> 💡 Many public models scale to zero and may return `503 no-instances` until they warm up. The\n> server retries automatically; if a model stays cold, pick another of the same kind.\n\n---\n\n## Development\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for setup, the build/test commands, and the Windows `#`-path\ncaveat. Quick version:\n\n```bash\nnpm ci\nnpm run check\n```\n\n## Security\n\nNever commit your API key. Credential-bearing requests are limited to HTTPS Chutes hosts, remote\nasset URLs are screened against private-network destinations, and file access is contained to the\nworkspace. Query strings and fragments are removed from network-error messages so signed asset URLs\nare not copied into logs. See [SECURITY.md](./SECURITY.md) for details and vulnerability reporting.\n\n## Migrating from 1.x\n\nVersion 2.0 makes the safety boundaries enforceable instead of best-effort:\n\n- Existing named assets are preserved unless `overwrite` / `--overwrite` is explicitly set.\n- Input and output paths must resolve inside the current workspace; symlink and junction escapes are\n  rejected.\n- Custom management API URLs require HTTPS, except loopback URLs used for local development. The\n  Chutes API key is never attached to custom or loopback management endpoints.\n- Management and invocation credentials are sent only to HTTPS Chutes hosts, and asset downloads\n  must resolve to public HTTPS destinations.\n- Responses and local input assets are capped by `CHUTES_MAX_ASSET_MB` (512 MiB by default).\n\nIf an existing automation intentionally replaces a file, add the explicit overwrite option after\nconfirming the target path.\n\n## Support\n\n- Ask usage questions in [GitHub Discussions](https://github.com/TheStreamCode/chutes-media-mcp/discussions).\n- Report reproducible bugs through [GitHub Issues](https://github.com/TheStreamCode/chutes-media-mcp/issues).\n- Report vulnerabilities privately by following [SECURITY.md](./SECURITY.md).\n\n## Author\n\nBuilt by **[Michael Gasperini](https://mikesoft.it)** — founder of [Mikesoft](https://mikesoft.it),\nbuilding small, focused, privacy-aware developer tools.\n\n[![Sponsor](https://img.shields.io/badge/Sponsor-EA4AAA?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/TheStreamCode)\n\nIf this project is useful to you, consider [sponsoring its development](https://github.com/sponsors/TheStreamCode).\n\n## License\n\nProject-owned code, documentation, and other project-created materials are\nlicensed under the [MIT License](LICENSE), except for the third-party rights\nbelow.\n\n## Third-party notices and provider terms\n\nThis independent project is not affiliated with, sponsored by, or endorsed by\nChutes Global Corp. The Chutes name, logo, platform, services, branding, and\nrelated marks are the property of Chutes Global Corp or their respective\nowners. The MIT License and this project grant no rights to use them.\n\n[`assets/chutes-media-mcp.png`](https://github.com/TheStreamCode/chutes-media-mcp/blob/main/assets/chutes-media-mcp.png) is the only\nproject image in this repository that incorporates Chutes logo/marks. It is one\nof exactly three user-created Chutes-logo image compositions across the Chutes\nprojects; the embedded Chutes logo/marks remain the property of their owner and\nare not licensed under MIT.\n\nThe MIT License does not grant rights in Chutes services or in third-party\nmodels, model content, or generated outputs. Their use is subject to applicable\nprovider terms and model licenses. Review Chutes' official [Terms of\nService](https://chutes.ai/terms) and [Privacy Policy](https://chutes.ai/privacy).\nSee [NOTICE](./NOTICE) for the packaged notice.\n",
  "bytes": 16733,
  "sha": "34d5571154994243ebfbef25fc3220c740a5ed38ff5cf995f09bd86d2add573a",
  "repo_slug": "thestreamcode/chutes-media-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_thestreamcode_chutes_media_mcp_41d86343/readme"
}