CraftStory MCP Server
OfficialThis MCP server generates and manages CraftStory talking-avatar videos, MiniMax H3 clips, and input audio clips through the CraftStory API.
List available video models, library/cloned voices, and custom avatars/scenes.
Create audio clips from text plus a voice, or by uploading a local recording.
Preview credit cost for CraftStory 2.0 videos before creating them.
Create CraftStory 2.0 talking videos from a photo/avatar scene plus ordered audio clips, with resolution, gestures, lipsync, and faceswap options.
Create MiniMax H3 clips from a photo in basic or reference mode, optionally lip-synced to an audio clip and with extra reference files/captions.
Check job status, wait with bounded polling, and retrieve finished job results with signed video/audio URLs.
Upscale finished CraftStory 2.0 or MiniMax H3 videos into a new job.
Note: the provided schema exposes only the tools above; the README also describes additional tools not present in this schema, such as image/music/sound-effect generation, cloud-video creation, and upload helpers.
Provides OAuth 2.1 authentication for the hosted MCP server via Auth0, validating access tokens against the configured Auth0 tenant's JWKS before forwarding requests to the CraftStory API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@CraftStory MCP Server make a talking-avatar video of ~/photos/portrait.jpg saying hello"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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, audio-driven with lip-sync, or the reference model without audio (the lines written in the description are voiced; extra photos keep a second person or a product consistent). 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-..."
}
}
}
}Related MCP server: MiniMax MCP JS
Install
claude.ai, Claude Desktop and mobile: hosted connector
No key and nothing to install; connectors belong to your Claude account, so one setup covers web, desktop and mobile. In claude.ai open Settings → Connectors → Add custom connector, paste
https://mcp.craftstory.com/mcp, open the advanced settings and set OAuth Client ID to
hAlwpyaDeO0CmuEKMibZxiXxtTT09NXL (public, no secret), then sign in with your CraftStory account. The
account needs a plan with API access (Producer). The hosted
server speaks Streamable HTTP with OAuth 2.1 (Auth0) and runs the same tools as the package below; local
file paths and chat attachments are not available there: pass a public URL, or let Claude call request_file_upload and drop the photo on the one-time upload page it returns.
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
Upload links (hosted mode and local alike): request_file_upload(kind=image|audio|video) → one-time page for the user → wait_for_upload / get_upload. Images: file_url goes into image_url, or the upload_id into create_image(image_upload_ids). Audio: upload_id goes into create_audio_clip(audio_upload_id). Audio/video: upload_id goes into reference_upload_ids of the MiniMax H3 tools. Limits: 20 MB for photos, 100 MB for audio and video.
list_models: Models, status (a paused model answers 503), limits and priceslist_voices: Library voices;include_clonedadds your cloned voiceslist_avatars: Your custom avatars, or the scenes of one avatarcreate_audio_clip: Speech from text + voice, or upload a local recordingpreview_cost: Credit estimate for a CraftStory 2.0 videocreate_craftstory2_video: Start a CraftStory 2.0 job (photo or avatar scene + audio clips)create_minimax_h3_video,create_minimax_h3_avatar_video: Start a MiniMax H3 job (basic, or reference mode with or without audio)create_cloud_video,preview_cloud_video_cost: A clip from a photo as the first frame with one of the cloud models:seedance-2.5(4-30 s),flux-3-video/flux-3-max(5-20 s, 720p/1080p),minimax-h3-maxandheygen-video(5-15 s, 480p/768p/1080p),gemini-omni-flash(3-10 s, 720p); the model writes and speaks its own soundtrackget_job_status: Status, percentage, failure reason, refund flagget_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 whilestateisrunningupscale_video: New job with the upscaled result (CraftStory 2.0 720p -> 1080p, H3 and the cloud models 2x)create_image: an image from a prompt, optionally from up to 8 of your pictures;modelnano-banana (10 credits, default), nano-banana-pro (39), seedream-5-pro (13) or flux-3 (14);aspect_ratio9:16, 16:9, 4:5, 1:1, 3:4, 4:3. The result'simage_urlgoes straight into the video toolscreate_music: Music track of 5-180 s from a description, instrumental by default (1 credit per second); a declined prompt comes back withprompt_suggestioncreate_sound_effect: Sound effect or ambience of 0.5-30 s (or auto length), optional seamless loop (1 credit per started 5 s, 2 minimum)
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.jpgsaying "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, or 768_960 for 4:5, 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).
Hosted server (operators)
craftstory-mcp-http serves the same tools over Streamable HTTP behind OAuth. Required env: MCP_PUBLIC_URL,
AUTH0_DOMAIN; optional MCP_AUDIENCE (defaults to <MCP_PUBLIC_URL>/mcp), CRAFTSTORY_API_BASE, PORT
(8788), MCP_ALLOWED_ORIGINS, MCP_TRUST_PROXY=1 behind a load balancer. Protected-resource metadata is at
/.well-known/oauth-protected-resource/mcp; access tokens are verified against the tenant's JWKS and forwarded
to the CraftStory API, nothing is stored. Dockerfile builds the production image.
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 testFull API reference: https://api.craftstory.com/api/v1/docs/public/ and the curl walkthrough at https://api.craftstory.com/api/v1/docs/samples/curl/.
Privacy Policy
This server runs on your machine and keeps no data of its own. It sends your API key and the inputs you pass to tools
(text, photos, audio, reference files) only to the CraftStory API at CRAFTSTORY_API_BASE (default
https://api.craftstory.com), where they are processed under the CraftStory privacy policy:
https://craftstory.com/privacy/. Generated videos and uploaded files are stored in your CraftStory account and can be
deleted there or via the API; nothing is retained locally by the server. No analytics or third-party services are
called by the server itself. Questions: support via https://craftstory.com/contacts/.
License
MIT
Available Tools
11 toolscreate_audio_clipCreate an audio clip (speech from text, or upload a recording)AInspect
The soundtrack every video model takes as input. Either text (up to 2000 characters) plus exactly one voice (voice_id from list_voices, or voice_user_id for a cloned voice), or file_path to upload a local WAV/MP3/M4A recording. Returns the clip id; it is ready when wait_for_job(model='audio-clip') reports done (usually seconds). Longer scripts: create several clips and pass all ids to create_craftstory2_video in order.
Inputs: text, voice_id, file_path, voice_user_id.
create_craftstory2_videoCreate a CraftStory 2.0 talking video (photo + audio)AInspect
Start a craftstory-2 generation: a photo of a person (image_url or image_path, or a custom avatar scene via scene_id) speaks the given audio clips with lip-sync, gestures and natural motion; any length. resolution is WIDTH_HEIGHT (480_832 / 720_1280 portrait, 832_480 / 1280_720 landscape); 1080p is available afterwards via upscale_video. Credits are charged on create (see preview_cost) and refunded if the job fails. Returns the job id and initial status; generation takes 8-15 minutes, so call wait_for_job(model='craftstory-2') repeatedly until it reports done, then get_job_result for the video URL.
Inputs: resolution (required), audio_clip_ids (required), name, faceswap, +7 more.
create_minimax_h3_videoCreate a MiniMax H3 clip (up to 15 s)AInspect
Start a minimax-h3 generation from one photo. mode='basic': user_prompt (scene description) + requested_duration_s (5-15); the model animates the photo and generates the soundtrack itself. mode='reference': the reference model. With audio_clip_id the clip is lip-synced to it (first 15 s billed) and user_prompt is optional. Without audio_clip_id, pass requested_duration_s and a user_prompt with the spoken line in quotes: the model voices it and generates the soundtrack. Either way up to 8 extra image / 3 video / 2 audio reference_files with reference_captions keep a second person, a product or a background consistent. Output is 768 px on the short side, orientation follows the photo. Cost 3.3 credits per billed second, charged on create. Returns the job id; call wait_for_job(model='minimax-h3') until done (1-3 min).
Inputs: mode (required), name, image_url, image_path, +5 more.
get_job_resultGet a finished job (video URL and details)ARead-onlyInspect
Full record of a job. For craftstory-2 the video is in video, for minimax-h3 in video_url, for audio clips in file; all are signed URLs valid for 7 days (call again for a fresh link). Also returns the parameters used and the credits charged.
Inputs: id (required), model (required).
get_job_statusGet a job's statusARead-onlyInspect
Status of a video job or audio clip: status, status_percentage, status_failed, credits_refunded. Terminal states: done; failed*, rejected_* and not_pass_moderation (audio) are failures. Prefer wait_for_job, which polls for you.
Inputs: id (required), model (required).
list_avatarsList custom avatars (and their scenes)ARead-onlyInspect
Custom avatars trained in the CraftStory app that craftstory-2 can generate with (pass an id as avatar_id). Each avatar may carry a default voice {id, voice_kind}: voice_kind 'user' means send it as voice_user_id, 'library' as voice_id in create_audio_clip. Pass avatar_id to list that avatar's scenes; a scene id can replace the photo (scene_id) in create_craftstory2_video.
Inputs: avatar_id.
list_modelsList CraftStory video modelsARead-onlyInspect
Catalogue of the video models behind this server with their status, modes, limits and credit prices. Two models today: craftstory-2 (a talking video of any length from one photo plus an audio clip; 8-15 min) and minimax-h3 (a clip of up to 15 s from one photo, either description-driven with generated sound or audio-driven with lip-sync; 1-3 min). Call this first when unsure which model fits, or to check that a model is not paused.
Inputs: no named parameters.
list_voicesList voices for text-to-speechARead-onlyInspect
Library voices (id, name, language, gender) usable as voice_id in create_audio_clip. With include_cloned=true also returns the account's own cloned voices, usable as voice_user_id. Voices are cloned in the CraftStory app, not via the API.
Inputs: include_cloned.
preview_costEstimate the credit cost of a CraftStory 2.0 videoARead-onlyInspect
Credits a craftstory-2 job would cost for the given audio clips and settings, without creating anything. Rate per second of audio: 480p 2.2 (2 with lipsync_mode=empty), 720p 3.3 (3 with empty); rounded up per job. MiniMax H3 is a flat 3.3 credits per billed second.
Inputs: resolution (required), audio_clip_ids (required), lipsync_mode.
upscale_videoUpscale a finished video (new job)AInspect
Creates a NEW job with the upscaled result; the original stays. craftstory-2: only 720p sources, resolution 1080_1920 (from 720_1280) or 1920_1080 (from 1280_720). minimax-h3: always 2x, no resolution needed. Costs 0.2 credits per second. Poll the returned id with wait_for_job.
Inputs: id (required), model (required), resolution.
wait_for_jobWait for a job (bounded polling)ARead-onlyInspect
Polls a job's status every few seconds for up to timeout_s (default 45, max 55 - most MCP clients cut a tool call at 60 s) and returns as soon as it is terminal. If it returns state='running', call it again - craftstory-2 jobs take 8-15 minutes, minimax-h3 1-3 minutes, audio clips seconds. Reports progress notifications when the client supports them.
Inputs: id (required), model (required), timeout_s.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Most tools have clearly distinct purposes, but get_job_status and wait_for_job overlap in polling job status. The descriptions mitigate this by recommending wait_for_job for terminal states, and get_job_result is clearly separate as a full record retrieval.
All tool names use snake_case with a verb_noun pattern, including model-specific create tools like create_minimax_h3_video and create_craftstory2_video. The convention is applied consistently across the entire set.
Eleven tools are well-scoped for a video generation service, covering model discovery, asset listing, audio creation, video creation, job management, cost preview, and upscaling. Each tool has a clear role and none feels redundant or out of place.
The surface covers the core generation lifecycle: create audio clips, create videos from two models, poll jobs, retrieve results, preview costs, list models/voices/avatars, and upscale. Minor gaps exist, such as no job cancellation or history listing, but agents can work around these for most workflows.
Maintenance
Related MCP Connectors
AI video, image and audio generation with 140+ AI models from any MCP agent
Plan, compare, price, generate, and recover AI video from compatible MCP clients.
Turn documents and photos into narrated AI videos from Claude, ChatGPT, Codex or any MCP client.
Create and manage AI image and video generations through Quriov's fixed public MCP tools.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceExposes video generation and editing tools to MCP-capable clients, enabling text-to-video, image-to-video, video editing, reusable voice and character profiles, and task status queries through natural language.4MIT
- AlicenseNot gradedqualityAmaintenanceEnables MCP-compatible clients to generate images and videos, synthesize speech, clone and design voices, and dynamically configure API interactions.635 npmMIT
- AlicenseBqualityCmaintenanceEnables any MCP-compatible AI agent to generate videos and images from text or reference frames, chain scenes into seamless multi-scene films with sound and speech, and download finished media with manifests and previews. It also exposes account status, plan limits, history and library management through confirm-gated, safe-by-default operations.2634MIT
- AlicenseNot gradedqualityAmaintenanceEnables MCP-compatible clients to generate images and videos, synthesize speech, clone voices, and design custom voices through the provider's APIs.635 npmMIT