Chutes Media MCP

Chutes Media MCP

通过 Chutes 从任意编码 Agent 生成图像、视频、音乐和语音，并将素材直接保存到你正在使用的项目中。

Chutes Media MCP 是一个模型上下文协议（MCP）服务和命令行界面（CLI），可让编码 Agent 使用 Chutes 媒体模型。它以标准输入/输出（stdio）MCP 服务的形式提供，也提供适用于不支持 MCP 的 Agent 的轻量 CLI，以及一个内置 Agent Skill，用于描述后再生成的工作流。

服务不会为每个模型硬编码请求载荷，而是获取模型的实时架构，并在消耗 GPU 调用前验证每个请求，然后将素材和来源记录写入工作区。它适用于 Claude Code、Cursor、Cline、Windsurf、Codex、OpenCode 和 Claude Desktop。

这是一个独立的社区项目，与 Chutes 无关联，未获其赞助或认可。

安装

无需全局安装，即可通过 npm 运行服务：

npx -y chutes-media-mcp

全局安装，将两个二进制文件添加到路径中：

npm install -g chutes-media-mcp

将服务注册到 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，请添加 docs/mcp-and-cli.md 中说明的 mcpServers 条目。也支持从 GitHub 而非 npm 运行：npx -y github:TheStreamCode/chutes-media-mcp。从 1.x 升级？请参阅 docs/migration-2.0.md。

快速开始

1. 在 chutes.ai 创建 Chutes API 密钥，并按“安装”部分的说明注册服务。
2. 请求 Agent 创建素材：“生成一张具有电影感的雾山山脉主视觉图，并将其保存在此项目中。”
3. Agent 会发现合适的模型、读取其实时架构、验证载荷，并将结果保存在 assets/chutes/image/ 下。返回的路径可直接在代码中引用。

同样的描述后再生成流程也可通过 shell 使用 chutes-media CLI。有关工具参考、CLI 示例和图像编辑，请参阅 docs/mcp-and-cli.md。

功能

• 支持四种媒体类型（图像、视频、音乐、语音）；当模型提供 img2img 或 inpaint 等编辑 cord 时，还支持图像编辑。
• 实时模型契约：运行时获取 cords 和输入架构，绝不硬编码。
• 发起任何 GPU 调用前，都会根据实时架构验证载荷。
• 文件访问限定在工作区内；除非明确设置 overwrite，否则会保留现有素材。
• 每个素材都附有来源记录文件，包含模型、cord、参数和架构哈希。
• 对可缩容至零的模型，自动进行冷启动重试并采用退避策略。
• 为耗时较长的视频和音乐任务提供进度更新。
• MCP 服务和 CLI 共用一个核心，因此两者的行为一致。

要求

• 已发布的服务和 CLI 要求 Node.js 20.3 或更高版本。Node.js 20 已停止维护；生产环境请使用 Node.js 22 或 24 LTS。
• Chutes API 密钥。
• 使用锁定工具链的贡献者需要 Node.js ^20.19.0、>= 22.13.0 或 >= 24。

配置

变量	必需	默认值	用途
CHUTES_API_KEY	是	无	Chutes API 密钥。从环境中读取；绝不写入磁盘。
CHUTES_AUTH_SCHEME	否	raw	在 Authorization 中发送密钥的方式：raw（密钥原样发送）或 bearer（值前加上 Bearer 和一个空格）。遇到 401 时，尝试另一种方式。
CHUTES_API_BASE_URL	否	https://api.chutes.ai	管理 API 的基本 URL。除本地回环开发外，必须使用 HTTPS；自定义端点永远不会收到 Chutes API 密钥。
CHUTES_OUTPUT_DIR	否	assets/chutes	Agent 工作目录中的输出目录。会追加 <kind>/ 子文件夹。
CHUTES_WARMUP	否	true	调用模型前预热模型。设为 false 可跳过预热。
CHUTES_COLD_START_RETRIES	否	4	冷启动模型返回 503 no-instances 时的重试次数。0 表示禁用重试。
CHUTES_COLD_START_BACKOFF_MS	否	8000	冷启动重试之间的基础退避时间；会随尝试次数增加。
CHUTES_MAX_ASSET_MB	否	512	保留在内存中的响应或本地输入资源的最大大小。上限为 4096。
CHUTES_PROGRESS_INTERVAL_MS	否	5000	调用阻塞时发送进度心跳的频率。
CHUTES_ALLOW_UNKNOWN_PARAMS	否	false	设为 true 时，接受模型架构中未列出的参数。默认情况下会拒绝这些参数，以便字段重命名时能明确报错。
CHUTES_PROVENANCE	否	true	写入包含模型、cord、参数和架构哈希的 <asset>.json 附属文件。设为 false 可禁用。

生成的资源会保存在 ./assets/chutes/<kind>/ 下，该路径相对于 Agent 的运行目录，因此文件会位于项目内。系统会拒绝路径遍历和符号链接逃逸；除非启用覆盖，否则会保留现有文件。

隐私与安全

API 密钥从 CHUTES_API_KEY 读取并保存在内存中。携带凭据的请求只会发送到 Chutes 的 HTTPS 主机；远程资源 URL 会经过筛查，以排除私有网络目标；文件访问范围限制在工作区内。网络错误消息会移除查询字符串和片段，避免签名资源 URL 出现在日志中。本项目不收集遥测数据。报告问题请参阅 SECURITY.md。

故障排除

Chutes 请求返回 401

密钥缺失、无效，或使用了错误的身份验证方案。确认启动服务的进程已设置 CHUTES_API_KEY，然后将 CHUTES_AUTH_SCHEME 设为 bearer 或 raw，选择与当前值不同的那个。

模型返回 503 no-instances

模型已缩容至零，Chutes 当前没有可用实例。服务器会自动重试； 如果等待时间过短，请增大 CHUTES_COLD_START_RETRIES 和 CHUTES_COLD_START_BACKOFF_MS，或 选择同类型的其他模型。

生成失败，提示参数未知或被拒绝

实时模型架构已更改，或参数名称有误。请再次调用 describe_media_model，并根据当前架构 重新构建请求负载。CHUTES_ALLOW_UNKNOWN_PARAMS=true 是临时变通方案，并非修复方法。

资源写入被拒绝

所有输入和输出路径都必须解析到当前工作区内，并且不会隐式替换现有文件。检查目标路径后， 传入显式的 overwrite 选项（或在 CLI 中使用 --overwrite）。

开发

要求：Node.js ^20.19.0、>= 22.13.0，或 >= 24，且需安装 npm。

git clone https://github.com/TheStreamCode/chutes-media-mcp
cd chutes-media-mcp
npm ci
npm run check

npm run check 会运行格式检查、lint、类型检查、覆盖率测试和构建。 CONTRIBUTING.md 介绍了 Windows 路径注意事项和选择加入的实时测试。

支持

请在 GitHub Discussions 中提问使用相关问题， 在 GitHub Issues 中报告可复现的缺陷， 并按照 SECURITY.md 中的说明私下报告安全漏洞。

贡献

请参阅 CONTRIBUTING.md。拉取请求必须通过所有必需的 CI 检查。

许可证

MIT——详见 LICENSE。第三方声明见 NOTICE。

---

由 Michael Gasperini (Mikesoft) 维护。 如果这个项目对你有帮助，请考虑赞助其维护工作。