@craftstory/mcp

CraftStory MCP server

Generate talking-avatar videos from Claude, Cursor, Claude Code or any other MCP client, using the CraftStory API:

• CraftStory 2.0 - a talking video of any length from one photo plus an audio clip (script + voice, your own recording, or a custom avatar). 8-15 minutes per video.
• MiniMax H3 - a clip of up to 15 s from one photo: description-driven with generated sound, or audio-driven with lip-sync. 1-3 minutes.

You need Node.js 20 or newer, a CraftStory account on a plan with API access, and an API key (app: Account -> API Access, keys look like sk-cs-...). Generations are billed in credits exactly like in the app; failed jobs are refunded.

Install

Claude Code

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

(--scope user makes it available in every project; drop it to install for the current project only.)

Claude Desktop

Add to claude_desktop_config.json (Settings -> Developer -> Edit Config), then restart Claude Desktop; the server shows up under the tools icon:

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

Cursor / other clients

Same shape in ~/.cursor/mcp.json (user-level, so the key never lands in a repository): command npx, args ["-y", "@craftstory/mcp"], env CRAFTSTORY_API_KEY. In a project-level .cursor/mcp.json prefer "CRAFTSTORY_API_KEY": "${env:CRAFTSTORY_API_KEY}" and keep the real key in your shell environment.

Environment variables: CRAFTSTORY_API_KEY (required), CRAFTSTORY_API_BASE (optional, default https://api.craftstory.com/api/v1; must be https unless CRAFTSTORY_ALLOW_HTTP=1).

Tools

Tool	What it does
list_models	Models, status (a paused model answers 503), limits and prices
list_voices	Library voices; include_cloned adds your cloned voices
list_avatars	Your custom avatars, or the scenes of one avatar
create_audio_clip	Speech from text + voice, or upload a local recording
preview_cost	Credit estimate for a CraftStory 2.0 video
create_craftstory2_video	Start a CraftStory 2.0 job (photo or avatar scene + audio clips)
create_minimax_h3_video	Start a MiniMax H3 job (basic or reference mode)
get_job_status	Status, percentage, failure reason, refund flag
get_job_result	Full record with the signed video URL (valid 7 days)
wait_for_job	Bounded polling (default 45 s, max 55 s); call again while state is running
upscale_video	New job with the upscaled result (CraftStory 2.0 720p -> 1080p, H3 2x)

Plus the prompt talking_video_from_photo (script + photo) that walks the model through the whole flow.

Example

Make a portrait video of the person in /Users/me/photos/portrait.jpg saying "Welcome to our spring collection", calm gestures.

The assistant will: list_voices -> create_audio_clip -> wait_for_job(audio-clip) -> preview_cost -> create_craftstory2_video (resolution 720_1280, gestures calm) -> wait_for_job(craftstory-2) a few times -> get_job_result -> the video URL.

Long jobs: wait_for_job returns within timeout_s (default 45 s, max 55 s) plus a few seconds for the final result fetch; every request inside it is capped by the time left, so it stays under the 60 s tool-call limit of most clients. A CraftStory 2.0 video needs several calls; that is by design so agent runtimes do not time out. A CraftStory 2.0 video needs several calls; that is by design so agent runtimes do not time out.

Local files vs URLs

Photos accept image_url (JPG/PNG) or image_path (absolute path or ~/...; JPG/PNG/HEIC, up to 20 MB, uploaded as multipart). Recordings and extra references are local paths too. Anything you pass as a path is uploaded to the CraftStory API, so keep your client's tool-approval prompts on (see SECURITY.md).

Development

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

Full API reference: https://api.craftstory.com/api/v1/docs/public/ and the curl walkthrough at https://api.craftstory.com/api/v1/docs/samples/curl/.

License

MIT