vivid-mcp

MCP server for VIVID — the AI content studio for e-commerce. Connect your VIVID account to Claude Desktop, Claude Code, Cursor or any Model Context Protocol 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_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 → 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, 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:

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

// 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, 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/ (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/; 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 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

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

Claude Desktop

claude_desktop_config.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.

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

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):

• 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.