CraftStory

CraftStory MCP 服务

通过 Claude、Cursor、Claude Code 或任何其他 MCP 客户端，使用 CraftStory API 生成会说话的头像视频：

• CraftStory 2.0 - 只需一张照片和一个音频片段，即可生成任意时长的会说话的视频（脚本 + 语音、你自己的录音或自定义头像）。每个视频需要 8-15 分钟。
• MiniMax H3 - 根据一张照片生成最长 15 s 的片段：基于描述并生成声音、基于音频并进行口型同步，或使用不带音频的参考模型（描述中写出的台词会被配音；额外的照片可让第二个人物或产品保持一致）。需要 1-3 分钟。

你需要 Node.js 20 或更高版本、拥有 API 访问权限套餐的 CraftStory 账户，以及 API 密钥（应用中：Account -> API Access；密钥格式为 sk-cs-...）。生成任务按与应用中完全相同的方式扣除积分；失败的任务会退还积分。

配置

所有客户端（Claude Desktop、Cursor、Windsurf、VS Code、Zed……）使用相同的标准 MCP 配置：

{
  "mcpServers": {
    "craftstory": {
      "command": "npx",
      "args": ["-y", "@craftstory/mcp"],
      "env": {
        "CRAFTSTORY_API_KEY": "sk-cs-..."
      }
    }
  }
}

安装

claude.ai、Claude Desktop 和移动端：托管连接器

无需密钥，也无需安装任何内容；连接器归属于你的 Claude 账户，因此设置一次即可用于 Web、桌面端和移动端。在 claude.ai 中打开 Settings → Connectors → Add custom connector，粘贴 https://mcp.craftstory.com/mcp，打开高级设置，并将 OAuth Client ID 设置为 hAlwpyaDeO0CmuEKMibZxiXxtTT09NXL（公开，无密钥），然后使用你的 CraftStory 账户登录。该 账户需要拥有 API 访问权限的套餐（Producer）。托管 服务使用带 OAuth 2.1（Auth0）的 Streamable HTTP，并提供与下方程序包相同的工具；此处无法访问本地 文件路径和聊天附件：请传入公开 URL，或让 Claude 调用 request_file_upload，然后在其返回的一次性上传页面上提交照片。

Claude Code

claude mcp add --scope user craftstory -e CRAFTSTORY_API_KEY=sk-cs-... -- npx -y @craftstory/mcp

（--scope user 会让它在每个项目中都可用；移除该参数即可仅为当前项目安装。）

Claude Desktop

将以下内容添加到 claude_desktop_config.json（Settings -> Developer -> Edit Config），然后重启 Claude Desktop；该服务会显示在工具图标下：

{
  "mcpServers": {
    "craftstory": {
      "command": "npx",
      "args": ["-y", "@craftstory/mcp"],
      "env": { "CRAFTSTORY_API_KEY": "sk-cs-..." }
    }
  }
}

Cursor / 其他客户端

在 ~/.cursor/mcp.json 中使用相同格式（用户级，因此密钥不会进入代码仓库）：命令为 npx，参数为 ["-y", "@craftstory/mcp"]，环境变量为 CRAFTSTORY_API_KEY。在项目级 .cursor/mcp.json 中，建议使用 "CRAFTSTORY_API_KEY": "${env:CRAFTSTORY_API_KEY}"，并将实际密钥保存在 shell 环境中。

环境变量：CRAFTSTORY_API_KEY（必需）、CRAFTSTORY_API_BASE（可选，默认值为 https://api.craftstory.com/api/v1；必须使用 https，除非 CRAFTSTORY_ALLOW_HTTP=1）。

工具

上传链接（托管模式和本地模式均适用）：request_file_upload(kind=image|audio|video) → 面向用户的一次性页面 → wait_for_upload / get_upload。图片：将 file_url 传入 image_url，或将 upload_id 传入 create_image(image_upload_ids)。音频：将 upload_id 传入 create_audio_clip(audio_upload_id)。音频/视频：将 upload_id 传入 MiniMax H3 工具的 reference_upload_ids。限制：照片 20 MB，音频和视频 100 MB。

• list_models：模型、状态（暂停的模型会返回 503）、限制和价格
• list_voices：语音库；include_cloned 会添加你克隆的语音
• list_avatars：你的自定义数字人，或某个数字人的场景
• create_audio_clip：用文本和语音生成语音，或上传本地录音
• preview_cost：预估 CraftStory 2.0 视频的费用
• create_craftstory2_video：启动 CraftStory 2.0 任务（照片或数字人场景 + 音频片段）
• create_minimax_h3_video、create_minimax_h3_avatar_video：启动 MiniMax H3 任务（基础模式，或有音频/无音频的参考模式）
• create_cloud_video、preview_cloud_video_cost：以照片作为首帧，使用某个云端模型生成视频片段：seedance-2.5（4-30 s）、flux-3-video / flux-3-max（5-20 s，720p/1080p）、minimax-h3-max 和 heygen-video（5-15 s，480p/768p/1080p）、gemini-omni-flash（3-10 s，720p）；模型会自行创作并生成配音
• get_job_status：状态、百分比、失败原因、退款标记
• get_job_result：包含签名视频 URL 的完整记录（有效期 7 天）
• wait_for_job：有时限的轮询（默认 45 s，最长 55 s）；当 state 为 running 时再次调用
• upscale_video：创建新任务并返回升格后的结果（CraftStory 2.0：720p → 1080p；H3 和云端模型：2x）
• create_image：根据提示词生成图片，也可使用最多 8 张你的图片；model 可选 nano-banana（10 个积分，默认）、nano-banana-pro（39 个积分）、seedream-5-pro（13 个积分）或 flux-3（14 个积分）；aspect_ratio 可选 9:16、16:9、4:5、1:1、3:4、4:3。生成结果的 image_url 可直接传入视频工具
• create_music：根据描述生成 5-180 s 的音乐曲目，默认纯音乐（每秒 1 个积分）；被拒绝的提示词会返回 prompt_suggestion
• create_sound_effect：生成 0.5-30 s 的音效或环境音（也可自动确定时长），可选无缝循环（每开始 5 s 消耗 1 个积分，最低 2 个）

另有提示词 talking_video_from_photo（脚本 + 照片），可引导模型完成整个流程。

示例

制作一段人物竖屏视频，让 /Users/me/photos/portrait.jpg 中的人用平静的手势说“欢迎来到我们的春季系列”。

助手将：list_voices → create_audio_clip → wait_for_job(audio-clip) → preview_cost → create_craftstory2_video（分辨率 720_1280，或 4:5 时使用 768_960，手势 calm）→ 多次调用 wait_for_job(craftstory-2) → get_job_result → 视频 URL。

耗时较长的任务：wait_for_job 会在 timeout_s（默认 45 s，最长 55 s）内返回，获取最终结果还需几秒；其中每个请求的时限都不会超过剩余时间，因此总时长低于大多数客户端的 60 s 工具调用限制。CraftStory 2.0 视频需要多次调用；这是有意设计的，可避免 Agent 运行时超时。CraftStory 2.0 视频需要多次调用；这是有意设计的，可避免 Agent 运行时超时。

本地文件与 URL

照片可使用 image_url（JPG/PNG）或 image_path（绝对路径或 ~/...；JPG/PNG/HEIC，最大 20 MB，以 multipart 方式上传）。录音和额外参考文件也可使用本地路径。你以路径形式传入的所有内容都会上传到 CraftStory API，因此请保持客户端的工具审批提示开启（参见 SECURITY.md）。

托管服务（运营者）

craftstory-mcp-http 通过 OAuth 在 Streamable HTTP 上提供相同的工具。必需的环境变量：MCP_PUBLIC_URL、 AUTH0_DOMAIN；可选的环境变量：MCP_AUDIENCE（默认为 <MCP_PUBLIC_URL>/mcp）、CRAFTSTORY_API_BASE、PORT （8788）、MCP_ALLOWED_ORIGINS，以及在负载均衡器后方设置的 MCP_TRUST_PROXY=1。受保护资源元数据位于 /.well-known/oauth-protected-resource/mcp；访问令牌会根据租户的 JWKS 进行验证，并转发到 CraftStory API，不会存储任何内容。Dockerfile 用于构建生产镜像。

开发

npm install
npm run build
CRAFTSTORY_API_KEY=sk-cs-... npm run smoke       # live check over stdio: lists tools, makes an audio clip, previews cost
# add "-- --h3" and SMOKE_IMAGE=/path/to/photo.jpg to also render a 5 s MiniMax H3 clip (costs 17 credits)
npm test

完整的 API 参考：https://api.craftstory.com/api/v1/docs/public/，以及 curl 演示：https://api.craftstory.com/api/v1/docs/samples/curl/。

隐私政策

此服务在你的计算机上运行，不会自行保留任何数据。它仅将你的 API 密钥以及你传递给工具的输入 （文本、照片、音频、参考文件）发送到 CRAFTSTORY_API_BASE（默认为 https://api.craftstory.com）上的 CraftStory API，并由该 API 按照 CraftStory 隐私政策进行处理： https://craftstory.com/privacy/。生成的视频和上传的文件会存储在你的 CraftStory 帐户中，可在帐户中或通过 API 删除；服务不会在本地保留任何内容。服务本身不会调用分析服务或第三方服务。 如有疑问，请通过 https://craftstory.com/contacts/ 联系支持团队。

许可证

MIT