Talking-avatar videos from a photo (CraftStory 2.0) and short clips with sound (MiniMax H3).
Generate talking-avatar videos from Claude, Cursor, Claude Code or any other MCP client, using the CraftStory API:
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.
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-..."
}
}
}
}
No key and nothing to install. In claude.ai open Settings → Connectors → Add custom connector, paste
https://mcp.craftstory.com/mcp, then sign in with your CraftStory account and allow access. The hosted
server speaks Streamable HTTP with OAuth 2.1 (Auth0) and runs the same tools as the package below; local
file paths are not available there, pass public URLs instead.
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.)
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-..." }
}
}
}
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).
list_models: Models, status (a paused model answers 503), limits and priceslist_voices: Library voices; include_cloned adds 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)get_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 while state is runningupscale_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.
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, 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.
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).
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.
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/.
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/.
MIT
Source-derived launch command. Check the maintainer’s required arguments and credentials before running:
npx -y @craftstory/mcpMerge this template into ~/Library/Application Support/Claude/claude_desktop_config.json. Keep existing servers. Add any arguments, credentials, and permissions required by the maintainer; this template has not been install-tested.
{
"mcpServers": {
"io-github-itseez3d-craftstory-mcp": {
"command": "npx",
"args": [
"-y",
"@craftstory/mcp"
]
}
}
}Restart Claude Desktop completely for changes to take effect. Confirm the server appears connected in the client’s tool list, then try a read-only example from its documentation.
Claude Desktop setup reference@craftstory/mcpnpmCraftStory works with any MCP-compatible client. Copy the config snippet from the Configuration section above and add it to the file shown for your client, then restart the application.
~/Library/Application Support/Claude/claude_desktop_config.jsonRestart Claude Desktop completely for changes to take effect.~/.cursor/mcp.jsonRestart Cursor for changes to take effect..vscode/mcp.jsonReload VS Code window for changes to take effect.~/.codeium/windsurf/mcp_config.jsonRestart Windsurf for changes to take effect..mcp.jsonSave at the project root, then start Claude Code in that project and review the MCP server approval prompt. Keep real credentials out of shared files.