# CraftStory MCP server

Generate talking-avatar videos from Claude, Cursor, Claude Code or any other [MCP](https://modelcontextprotocol.io) client, using the [CraftStory](https://craftstory.com) 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...):

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

## 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

```bash
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:

```json
{
  "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 prices
- `list_voices`: Library voices; `include_cloned` adds your cloned voices
- `list_avatars`: Your custom avatars, or the scenes of one avatar
- `create_audio_clip`: Speech from text + voice, or upload a local recording
- `preview_cost`: Credit estimate for a CraftStory 2.0 video
- `create_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 flag
- `get_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 `running`
- `upscale_video`: New job with the upscaled result (CraftStory 2.0 720p -> 1080p, H3 2x)
- `create_image`: Nano Banana image from a prompt, optionally from up to 8 of your pictures; `aspect_ratio` 9:16, 16:9, 4:5, 1:1, 3:4, 4:3 (13 credits, 25 with `nano-banana-pro`). The result's `image_url` goes straight into the video tools
- `create_music`: Music track of 5-180 s from a description, instrumental by default (1 credit per second); a declined prompt comes back with `prompt_suggestion`
- `create_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.jpg` saying "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

```bash
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/.

## 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