CraftStory MCP server

Make talking-avatar videos from Claude, Cursor and any AI agent that speaks the Model Context Protocol. One photo and a script in, a lip-synced video with natural gestures out — through tools your assistant calls for you.

What your assistant can do with it

Talking videos from a photo — "make a portrait video of this person saying our spring-collection announcement": the assistant picks a voice, synthesizes the script, generates the video with CraftStory 2.0 and hands you the link. Any length, up to 30 minutes.
Short clips with generated sound — describe a scene and get a 5–15 s clip from one photo with MiniMax H3; or drive it with your own audio for lip-sync.
Your voices and avatars — library voices, voices you cloned in the app, and custom avatars are all listable and usable as tools.
Batches inside a workflow — a coding agent can loop over leads, scripts or product shots and produce one video per row, polling each job without blocking.

Install

You need Node.js 20+, a CraftStory plan with API access and an API key (app → Account → API Access, keys look like sk-cs-...). The server is an npm package; every client below runs it with npx.

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

# Claude Desktop — Settings → Developer → Edit Config (claude_desktop_config.json), then restart { "mcpServers": { "craftstory": { "command": "npx", "args": ["-y", "@craftstory/mcp"], "env": { "CRAFTSTORY_API_KEY": "sk-cs-..." } } } }

# Cursor — ~/.cursor/mcp.json (user level, so the key never lands in a repository) { "mcpServers": { "craftstory": { "command": "npx", "args": ["-y", "@craftstory/mcp"], "env": { "CRAFTSTORY_API_KEY": "sk-cs-..." } } } }

Windsurf, VS Code, Zed, Goose and other MCP clients take the same command/args/env triple. Full README with troubleshooting on GitHub.

Tools

Eleven tools, each a thin wrapper over one documented endpoint of the CraftStory API, plus a talking_video_from_photo prompt that walks the assistant through the whole flow.

Tool	What it does
`list_models`	Video models with status, limits and credit prices
`list_voices`	Library voices, plus your cloned voices
`list_avatars`	Custom avatars trained in the app, and their scenes
`create_audio_clip`	Speech from text in a chosen voice, or upload a recording
`preview_cost`	Credit estimate for a CraftStory 2.0 video before creating it
`create_craftstory2_video`	Start a CraftStory 2.0 talking video: photo (or avatar scene) + audio clips, portrait or landscape
`create_minimax_h3_video`	Start a MiniMax H3 clip: description-driven with generated sound, or audio-driven with lip-sync
`get_job_status`	Status, percentage, failure reason and refund flag of a job
`get_job_result`	Finished job with the signed video URL and the parameters used
`wait_for_job`	Bounded polling (up to 55 s per call) so the assistant can wait without hanging
`upscale_video`	New job with the upscaled result: CraftStory 2.0 720p → 1080p, MiniMax H3 2×

Example: from a photo to a talking video

Ask Claude:

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

What the assistant does with the tools, step by step:

list_voices → picks a voice that fits the script.
create_audio_clip with the script and that voice → wait_for_job until the clip is ready (seconds).
preview_cost → tells you the credit price before spending anything.
create_craftstory2_video with the photo, the clip, resolution 720_1280 and gestures calm.
wait_for_job a few times while the video renders (8–15 minutes), reporting progress.
get_job_result → the video URL, ready to download or share.

How it works, what it costs

Runs locally, talks only to CraftStory. The server is a small Node process on your machine; it sends your key and your inputs to api.craftstory.com over HTTPS and nothing anywhere else. Photos and recordings you pass as file paths are uploaded to your CraftStory account.
Same credits as the app. CraftStory 2.0: 2.2–3.3 credits per second of audio depending on resolution; MiniMax H3: 3.3 credits per billed second; upscale 0.2 credits per second. Failed jobs are refunded. Plans and packs on the pricing page.
Built for long jobs. Generation is asynchronous; wait_for_job never blocks a tool call for more than 55 seconds, so assistants with a 60-second tool limit keep working and simply call it again.
Open source, MIT. Source, issues and changelog on GitHub; the package is @craftstory/mcp on npm. Prefer raw HTTP? The REST API is what the server wraps.

FAQ

Frequently asked questions

What is the CraftStory MCP server?

An open-source Model Context Protocol server (npm package @craftstory/mcp) that exposes the CraftStory video API as tools. Any MCP client — Claude Desktop, Claude Code, Cursor, Windsurf, custom agents — can list voices, create audio clips and generate talking-avatar videos by calling those tools.

What do I need to use it?

Node.js 20 or newer, a CraftStory account on a plan with API access, and an API key from the app (Account → API Access, keys look like sk-cs-...). Videos use the same credits as in the app; failed jobs are refunded.

How long does a video take through MCP?

The same as in the app: a CraftStory 2.0 talking video takes 8–15 minutes, a MiniMax H3 clip 1–3 minutes. The server's wait_for_job tool polls in short slices so the assistant keeps control and can report progress instead of hanging on one call.

Does it cost extra?

No. The MCP server is free and open source (MIT). Generations are billed in CraftStory credits exactly like in the web app.

Can I use my own photo and voice?

Yes. Pass a local photo path or a public image URL; create speech from text in any library voice, use a voice cloned in the app, or upload your own recording. Custom avatars trained in the app are available through list_avatars.

Is my data sent anywhere else?

The server runs on your machine and talks only to the CraftStory API over HTTPS. It keeps nothing locally and calls no third-party services. See the privacy policy and the SECURITY notes in the repository.