CraftStory MCP server

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.

Config

Standard MCP configuration, identical for every client (Claude Desktop, Cursor, Windsurf, VS Code, Zed...):

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

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 claudedesktopconfig.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 CRAFTSTORYAPIKEY. In a project-level .cursor/mcp.json prefer "CRAFTSTORYAPIKEY": "${env:CRAFTSTORYAPIKEY}" and keep the real key in your shell environment.

Environment variables: CRAFTSTORYAPIKEY (required), CRAFTSTORYAPIBASE (optional, default https://api.craftstory.com/api/v1; must be https unless CRAFTSTORYALLOWHTTP=1).

Tools

• list_models: Models, status (a paused model answers 503), limits and prices
• listvoices: Library voices; includecloned adds your cloned voices
• list_avatars: Your custom avatars, or the scenes of one avatar
• createaudioclip: Speech from text + voice, or upload a local recording
• preview_cost: Credit estimate for a CraftStory 2.0 video
• createcraftstory2video: Start a CraftStory 2.0 job (photo or avatar scene + audio clips)
• createminimaxh3_video: Start a MiniMax H3 job (basic or reference mode)
• getjobstatus: Status, percentage, failure reason, refund flag
• getjobresult: Full record with the signed video URL (valid 7 days)
• waitforjob: 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 talkingvideofrom_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: listvoices -> createaudioclip -> waitforjob(audio-clip) -> previewcost -> createcraftstory2video (resolution 7201280, gestures calm) -> waitforjob(craftstory-2) a few times -> getjob_result -> the video URL.

Long jobs: waitforjob 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.

Shortened. The full README is on GitHub.