# vivid-mcp

MCP server for [VIVID](https://vividai.tv) — the AI content studio for e-commerce. Connect your VIVID account to Claude Desktop, Claude Code, Cursor or any [Model Context Protocol](https://modelcontextprotocol.io) client and generate images and videos, browse your gallery and manage jobs from the chat.

## What you can do

| Tool | What it does |
|---|---|
| `vivid_whoami` | Account linked to the key: plan, credits |
| `vivid_usage` | Monthly usage vs plan limits |
| `vivid_buy_credits` | Link where the user buys a credit pack or turns on auto top-up — the agent never pays, the user confirms in the browser |
| `vivid_list_models` | Image / video / LLM models with prices and capabilities |
| `vivid_generate_image` | Text-to-image (with optional product / person / context references), waits for the result |
| `vivid_generate_video` | Start a video (Seedance 2.5, Kling O3, MiniMax H3, Gemini Omni, LTX, Grok…) |
| `vivid_job_status` | Poll a job, get the asset and download URL |
| `vivid_list_jobs` | Recent generations |
| `vivid_list_assets` · `vivid_get_asset` | Browse the gallery |
| `vivid_download_asset` | Save an asset to a local folder |
| `vivid_share_asset` | Publish an asset and get a share link, toggle favorite |
| `vivid_upload_file` | Upload a local file or URL to use as reference / start frame / audio |
| `vivid_list_references` | Saved products (from product analysis) and testimonials / characters with names and ids — use the names in `vivid_generate_image` `products` / `testimonials`, like #Product / @Testimonial in the app |
| `vivid_analyze_product` · `vivid_create_testimonial` | Save a product from a photo (free, plan quota) or create a reusable testimonial from three photos or attributes (50 credits) — both then usable by name |
| `vivid_list_voices` | TTS providers and preset voices with credit cost |
| `vivid_chat` | One chat completion on VIVID's LLM routing — Grok, Claude, OpenAI GPT, Kimi (Wavespeed)  |
| `vivid_generate_music` · `vivid_music_status` · `vivid_list_music_providers` | Unique track from a brief — Suno V6 (default, 6 credits for two takes, exact length for instrumentals) or MiniMax Music 3.0 (14 credits, length is a hint, trim in the editor); vocals optional, charged when ready. Rendering takes 20 s–3 min: the tool waits up to `waitSec`, then returns a `taskId` for `vivid_music_status` |
| `vivid_analyze_audio` | Tempo (BPM, beat grid) and transient peaks of a music/voice file, computed server-side (free): the cut points for a dynamic montage, also used automatically by `CUT_TO_BEAT` (grid `beats` \| `peaks`) |
| `vivid_search_sounds` | Search Freesound.org for existing music, loops and sound effects (free). Commercial-safe licenses only by default (CC0, CC BY), with a ready attribution line for CC BY; returns MP3 preview URLs to drop into a timeline |
| `vivid_transcribe` | Speech-to-text (Deepgram Nova-3, free): per-word timestamps, readable cues, SRT/VTT export — from an asset, URL or local file |
| `vivid_retouch` | Edit ONE object of an image (text target, region or mask), rest byte-identical — 2–6 credits |
| `vivid_compare_product` | Visual QC of a render vs the SKU photo: match score, verdict, differences, fixPrompt — 1 credit |
| `vivid_product_sheet` | Reads the reference sheet of a saved product and the price of a new one (free) |
| `vivid_create_product_sheet` | Makes the reference sheet: front, two angles and worn, each checked against the real photo (one free redo, refund if it still fails) — 13 credits, first one free on the free plan |
| `vivid_generate_voice` | Text-to-speech: Gemini 3.1 Flash presets, MiniMax Speech 2.8 HD (presets, emotions, and voices the account holder saved in the VIVID web app after confirming they own the voice), OmniVoice voice design, Deepgram. It does not clone a voice from an audio file or URL |
| `vivid_list_projects` | Your projects |
| `vivid_list_editor_projects` | Saved video-editor timelines |
| `vivid_create_editor_project` · `vivid_get_editor_project` · `vivid_edit_timeline` | Build and edit video-editor timelines headless (clips, trims, speed, transitions, 16:9↔9:16, texts, masks, keyframes) with the same engine as the web editor — see *Timeline editing* |
| `vivid_render_project` · `vivid_render_status` | Queue an MP4 render of an editor project and poll it (see *Rendering* below) |
| `vivid_record_ui` | Screen-record a scripted walkthrough of vividai.tv (or any site) with a local Chromium — cursor, smooth moves, click ripples — and upload it as a video asset (see *UI recording* below) |

## Setup

1. Get an API key: sign in on [vividai.tv](https://vividai.tv) → **Settings** → **API key**.
2. Connect your client. Three ways, pick one:

| | How | Needs Node? | Local-only tools (`vivid_download_asset`, `vivid_record_ui`, local paths) |
|---|---|---|---|
| **Remote** | `https://mcp.vividai.tv/mcp` + `Authorization: Bearer vk_…` | no | no |
| **Connector (Claude.ai)** | `https://mcp.vividai.tv/mcp` with OAuth — no key to paste | no | no |
| **Connector (ChatGPT)** | `https://mcp.vividai.tv/chatgpt` with OAuth — no key to paste | no | no |
| **Claude Code plugin** | `/plugin install vivid@vivid` — OAuth, plus the VIVID skills | no | no |
| **Claude Desktop extension** | download [`vivid-mcp.mcpb`](https://vividai.tv/downloads/vivid-mcp.mcpb), double-click, paste the key | no (bundled runtime) | yes |
| **Local (npx)** | `npx -y vivid-mcp` with `VIVID_API_KEY` | Node.js 20+ | yes |
| **Command line** | `npx -y vivid-mcp call <tool> '<json>'` with `VIVID_API_KEY` — no MCP client | Node.js 20+ | yes |

### Remote (nothing to install)

The same server runs as a Cloudflare Worker at `https://mcp.vividai.tv/mcp` (Streamable HTTP, stateless). Send your API key on every request:

```bash
# Claude Code
claude mcp add --transport http vivid https://mcp.vividai.tv/mcp --header "Authorization: Bearer vk_xxx"
```

```json
// Cursor and other clients that take a URL + headers
{ "mcpServers": { "vivid": { "url": "https://mcp.vividai.tv/mcp", "headers": { "Authorization": "Bearer vk_xxx" } } } }
```

`GET https://mcp.vividai.tv/` answers with the version and the endpoint. Files must be public URLs (`vivid_upload_file` accepts a URL); `outputDir` / `outputPath` are ignored.

### Connectors: ChatGPT, Claude.ai (OAuth)

Clients that cannot send a header authenticate with OAuth 2.1 instead. Add a connector with the URL `https://mcp.vividai.tv/mcp` (Claude.ai → Settings → Connectors → Add custom connector) or `https://mcp.vividai.tv/chatgpt` (ChatGPT → Settings → Connectors → Create) and pick **OAuth**. The client discovers `/.well-known/oauth-protected-resource`, registers itself (dynamic client registration) and sends you to `vividai.tv/oauth/consent`, where you sign in and click **Authorize**. Each connector gets its own credential (`vc_…`, never your API key) that acts on your assets and credits but cannot change the password, rotate the API key or delete the account; revoke it any time from **Settings → Connected apps**.

`/chatgpt` serves the same tools under OpenAI's plugin guidelines: no `vivid_buy_credits` (an out-of-credits error points to the informational page [vividai.tv/credits](https://vividai.tv/credits), which has no checkout or upgrade button), no `vivid_chat`, no photos or recordings of a real person as inputs (`vivid_create_testimonial` takes `attributes` only, `vivid_generate_image` has no `modelImageUrls`, `vivid_generate_video` takes only audio made by `vivid_generate_voice` / `vivid_generate_music` and only gallery videos as references; every other image — frames, references, product and scene photos, retouch sources, `vivid_upload_file` — goes through the API's person check, which refuses a recognisable face). Replies leave out timestamps, raw project dumps, API paths and provider details.

### Claude Code plugin (OAuth + skills)

This repo is also a Claude Code plugin and its own marketplace. It connects to the remote server with OAuth (no key to paste) and adds the skills in [`skills/`](skills) (product photos, product video, brand cast):

```
/plugin marketplace add loopotv/vivid-mcp
/plugin install vivid@vivid
```

Then run `/mcp`, pick **vivid** and authenticate: the browser opens `vividai.tv/oauth/consent`. The manifest lives in [`.claude-plugin/`](.claude-plugin); its `version` must match `package.json` (a test checks it), because installed plugins only update when it changes. Check it with `claude plugin validate --strict .`.

### Claude Desktop (one-click extension)

Download [vivid-mcp.mcpb](https://vividai.tv/downloads/vivid-mcp.mcpb) and open it with Claude Desktop: it installs the server with its own Node runtime and asks for your API key (stored by Claude as a secret). Built with `npm run build && npx @anthropic-ai/mcpb pack` from `manifest.json`.

### Local (npx, Node.js 20+)

### Claude Code

```bash
claude mcp add vivid -e VIVID_API_KEY=vk_xxx -- npx -y vivid-mcp
```

### Claude Desktop

`claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "vivid": {
      "command": "npx",
      "args": ["-y", "vivid-mcp"],
      "env": { "VIVID_API_KEY": "vk_xxx" }
    }
  }
}
```

### Cursor / other clients

Same command: `npx -y vivid-mcp` with `VIVID_API_KEY` in the environment.

### Command line (no MCP client)

The same tools run from a shell, through an in-memory MCP client — same arguments, same validation, same results.
This is what the `vivid-studio` skill uses in agents that have a terminal but no MCP connection.

```bash
export VIVID_API_KEY=vk_xxx
npx -y vivid-mcp tools                       # every tool with its title
npx -y vivid-mcp schema generate_image       # description + JSON schema of the arguments
npx -y vivid-mcp call whoami                 # the vivid_ prefix is optional
npx -y vivid-mcp call generate_image '{"prompt":"…","model":"nano-banana-2"}'
npx -y vivid-mcp call edit_timeline @args.json   # or - to read stdin
```

The tool's text result goes to stdout; the exit code is 1 when the tool reports an error.

### Environment

| Variable | Required | Default |
|---|---|---|
| `VIVID_API_KEY` | yes | — |
| `VIVID_API_URL` | no | `https://vivid-api.vividoai.workers.dev` |

## Example prompts

- "Which video models do I have on VIVID and what do they cost?"
- "Generate 2 images of a leather handbag on a marble counter, 4:5, with nano-banana-2."
- "Upload ~/Desktop/bag.jpg and make a 10 s 9:16 video with Seedance 2.5 using it as the product reference. Tell me when it's done."
- "Download my last video to ~/Downloads and give me a public link."
- "Make a 30 s upbeat instrumental for a product film and save both takes to ./music."
- "Transcribe ./voiceover.mp3 in Italian and write word-level SRT to ./subs.srt."
- "Create a 9:16 editor project from my last two videos, cut each to 4 s with a dissolve between them, add the title 'New drop' for the first 3 s, then render it."
- "In my last generated image, make the ring on the ring finger a plain yellow gold band, then compare it with ./sku/ring-01.jpg and tell me if it passes."

## Timeline editing

`vivid_create_editor_project` / `vivid_edit_timeline` run the VIVID editor headless ([vivid-editor-core](https://www.npmjs.com/package/vivid-editor-core), the same store and AI-command orchestrator the web editor uses) and save the project to your account, so anything you build here opens in `vividai.tv/tools/editor` and renders with `vivid_render_project`. Commands are `{ type, payload }` objects (ADD_CLIP, UPDATE_CLIP, SPLIT_CLIP, SET_TRANSITION, SET_CANVAS_PRESET, ADD_TEXT, SET_ANIMATIONS, ADD_EFFECT, SET_MASK…) — the tool descriptions list them. Media is imported by VIVID asset id, URL or local path.

## UI recording

`vivid_record_ui` drives a local Chromium through [Playwright](https://playwright.dev) and records the session: you pass a list of steps (`goto`, `click`, `hover`, `type`, `fill`, `press`, `scroll`, `wait`, `hide`, `evaluate`, with Playwright selectors) and get back a crisp 2× video (2880×1800 for the default 1440×900 viewport) uploaded to your gallery, ready for `vivid_create_editor_project` / `vivid_edit_timeline`. The browser is logged into the account of `VIVID_API_KEY` automatically (the key is exchanged for a short-lived session through `POST /api/me/session`), a cursor with click ripples is drawn in-page, and the page-load lead is trimmed. Steps can be `optional` (skipped when their element is missing, e.g. a one-time onboarding dialog). No credits are charged.

Requirements on the machine running the MCP server: Google Chrome (or `npx playwright install chromium`) and, for MP4 output, `ffmpeg` on PATH (otherwise the raw webm is uploaded, which the editor renders fine). `playwright-core` is an optional dependency, loaded only when the tool is used.

## Rendering

VIVID's video editor renders in the browser (Canvas2D + WebCodecs), so `vivid_render_project` does not produce the file by itself: it queues a **render job** and returns an `openUrl`. Open that URL in a browser where you are logged into vividai.tv (or pass `openBrowser: true` to open it on this machine) — the editor loads the project, exports it and uploads the MP4 to your gallery. `vivid_render_status` reports progress and the final asset; `vivid_download_asset` fetches it.

## Credits

Every generation is charged in VIVID credits according to the model (per image, or credits/second × duration for video). `vivid_list_models` shows the exact prices; `vivid_whoami` shows your balance and whether auto top-up is on. Videos are pre-charged when the job starts.

Credits come from a plan or from **credit packs** (500 / 1,500 / 5,000 credits from €12.99, valid 12 months, no subscription needed). When credits run out mid-job, the failing call returns a top-up link: the agent shows it, you pay in the browser, the agent retries — finished work is kept. `vivid_buy_credits` returns the same link on demand, sized to the credits still missing. With **auto top-up** on (Billing page on vividai.tv) the job doesn't stop at all: below your threshold VIVID buys the same pack again on your saved card, within a monthly cap you set and at most 5 times a day. Nothing in the MCP can charge your card or switch auto top-up on.

## Development

```bash
npm install
npm run typecheck
npm test
npm run inspect   # opens the MCP Inspector against the built server
```

`npm run build` compiles to `dist/`; the `prepare` script runs it automatically when the package is installed from GitHub.

## License

MIT

## Skills

`skills/` holds the skill bundles (one folder, one `SKILL.md` each, [open SKILL.md format](https://learn.chatgpt.com/docs/build-skills)):

- `vivid-studio` — the whole studio in one skill: images, retouch and QC, video, voice, music, transcription,
  timeline editing and render, screen recording. `SKILL.md` routes to `references/*.md` per area and runs the
  tools through MCP when connected, otherwise through the command line above.
- `vivid-product-photos`, `vivid-product-video`, `vivid-brand-cast` — narrower skills submitted with the ChatGPT app.

They are plain instructions on top of the tools above — no code of their own.
Zip a skill folder (`cd skills && zip -r vivid-studio.zip vivid-studio`) to publish it on a skills marketplace.