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.
Cinematic clips from one photo — "turn this product shot into a 10-second 1080p clip with a slow push-in and a voice-over": the assistant picks Seedance 2.5, FLUX 3 Video or Max, MiniMax H3 Max, HeyGen Video 1.0 or Gemini Omni Flash, prices it first and hands you the clip; every one of them writes its own soundtrack.
The picture to start from — "make a 4:5 photo of a woman holding our serum in a bathroom, then make her talk": the assistant generates the frame with Nano Banana, optionally from your product shots, and passes it to the video tools.
Music and sound — "add a calm piano bed and the sound of a busy cafe": the assistant makes the track and the ambience and hands you the MP3s.
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

claude.ai, Claude Desktop and mobile: hosted connector, no key. Connectors belong to your Claude account, so one setup covers web, desktop and mobile. Open Settings → Connectors → Add custom connector, name it CraftStory, paste the URL and the OAuth Client ID below (the client id is public; there is no secret), then click Connect and sign in with your CraftStory account. Like the API, the connector needs a CraftStory plan with API access (Producer); custom connectors are available on Claude Pro, Max, Team and Enterprise plans.

# claude.ai — Settings → Connectors → Add custom connector URL: https://mcp.craftstory.com/mcp OAuth Client ID: hAlwpyaDeO0CmuEKMibZxiXxtTT09NXL (open the advanced settings; leave the client secret empty)

Step-by-step walkthrough with example prompts: How to make AI videos from Claude.

The hosted connector runs the same tools over Streamable HTTP with OAuth 2.1; pass photos as public URLs, or just say you want to use a photo from your phone or disk: Claude replies with a one-time upload link (valid 15 minutes), you drop the photo on that page and the clip starts. Chat attachments themselves do not reach the connector; audio still needs a URL, and the local setups below take file paths directly.

Claude Code, Cursor and other local MCP clients (also Claude Desktop if you want local file paths). 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, local server (optional: the connector above is simpler) — 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

Each tool is 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
`create_cloud_video`	A clip from a photo as the first frame with Seedance 2.5, FLUX 3 Video, FLUX 3 Max, MiniMax H3 Max, HeyGen Video 1.0 or Gemini Omni Flash; the model writes and speaks its own soundtrack; 3–30 s depending on the model, up to 1080p
`preview_cloud_video_cost`	Credit price of such a clip for a model, duration and resolution, before creating it
`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 and the six photo-to-video models 2×
`create_minimax_h3_avatar_video`	MiniMax H3 avatar mode: your custom avatar says your text in its own voice, 5–14 s
`create_image`	Nano Banana image from a prompt and up to 8 of your pictures, in 9:16, 16:9, 4:5, 1:1, 3:4 or 4:3; the result goes straight into the video tools
`create_music`	Music track of 5–180 s from a description, instrumental by default
`create_sound_effect`	Sound effect or ambience of 0.5–30 s, optionally a seamless loop
`request_file_upload`, `wait_for_upload`, `get_upload`	One-time upload link for a photo, recording or video the assistant cannot reach by URL

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: 4.2 credits per billed second (basic and reference modes), 5.6 in avatar mode; upscale 0.2 credits per second; an image 10 credits with Nano Banana (39 with Nano Banana Pro, 13 with Seedream 5.0 Pro, 14 with FLUX.3); music 1 credit per second; a sound effect 1 credit per started 5 seconds (2 minimum); photo-to-video clips per second of output: Seedance 2.5 14.7 / 33 / 60.9 (480p / 720p / 1080p), FLUX 3 Video and Max 15.8 / 26.9 (720p / 1080p), MiniMax H3 Max 4.7 / 7.5 / 14.9 (480p / 768p / 1080p), HeyGen Video 1.0 1.9 / 1.9 / 5.6, Gemini Omni Flash 9.5 (720p). 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, generate talking-avatar videos and short clips from a photo with Seedance, FLUX 3, MiniMax H3 Max, HeyGen or Gemini Omni by calling those tools.

Does it work in claude.ai without installing anything?

Yes. Add https://mcp.craftstory.com/mcp as a custom connector (Settings → Connectors) with the OAuth Client ID hAlwpyaDeO0CmuEKMibZxiXxtTT09NXL and sign in with your CraftStory account; no API key is needed, but the account must be on a plan with API access (Producer). CraftStory is not listed in the built-in connector directory, which does not include AI video generators, so it is added by URL.

What do I need to use it?

For the local server: 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, a Seedance 2.5 clip 3–10 minutes, FLUX 3 Video 2–5 minutes, the other photo-to-video models under a minute. 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.