io.github.egocen-vivideo/vivideo MCP Server

The io.github.egocen-vivideo/vivideo MCP server provides AI video generation using the Vivideo API. It supports both auto and manual modes, and includes capabilities for creating or using avatars and voices. It also covers brand kit support as part of the video generation workflow.

🛠️ Key Features

AI video generation via the Vivideo API
Auto mode and manual mode
Avatar support
Voice support
Brand kits

🚀 Use Cases

Generating AI videos with configurable settings
Creating videos using predefined or selected avatars
Producing voice-driven video outputs
Applying brand kits during video generation

⚡ Developer Benefits

Integrates with the Vivideo API for video generation
Exposes options for mode selection (auto/manual), avatars, voices, and brand kits

Vivideo Toolchain

The developer + agent integration layer for the Vivideo API — a shared client, an MCP server, a CLI, and Skills. Agents are a primary user, not an afterthought.

Everything sits on top of the public API (the source of truth). No backend business logic is duplicated here — the toolchain only adds client-side ergonomics and guardrails.

code

vivideo-toolchain/            npm workspaces monorepo (TypeScript)
├── packages/core   @vivideo/core   one typed API client + guardrails (shared)
├── packages/mcp    @vivideo/mcp    MCP server (stdio) — 13 agent tools
├── packages/cli    @vivideo/cli    `vivideo` CLI — humans, scripts, CI, agents
├── skills/                          reusable agent Skills (SKILL.md)
└── docs/                            installation, configuration, workflows

Architecture

One client, one set of types, derived from packages/core/openapi.yaml. The MCP server and CLI both call @vivideo/core — there is exactly one representation of each request/response, so the tools, CLI, docs and OpenAPI stay consistent.

@vivideo/core adds only client-side concerns, never business logic:

Guardrail	What it does
Rate limiting	Token-bucket cap on request rate (default 8/s) — the client can't become a request flood.
Concurrency cap	Semaphore limits in-flight requests (default 4).
Bounded retries	Retries only `retryable` failures, with full-jitter backoff, capped attempts.
Honors `Retry-After`	On 429 it waits the API-specified delay before retrying.
Idempotency	Every video-create sends an `Idempotency-Key`; retries reuse it → no duplicate charges.
Timeouts	Per-request `AbortController` timeout (default 30s).
Safe waiting	`waitForVideo` polls at the API's suggested interval, with a hard timeout — never a `while(true)`.
Secret redaction	API keys / signing secrets are stripped from every log, error, and output.

These complement — and never bypass — the API's own auth, rate limits, idempotency, credit checks, premium gates, ownership and error model.

Quick start

bash

# from the repo (until packages are published to npm)
npm install
npm run build

# authenticate (stored 0600 in ~/.vivideo/config.json), or use VIVIDEO_API_KEY
export VIVIDEO_API_KEY="vv_live_..."   # from https://app.vivideo.ai/account/api-keys

# CLI
node packages/cli/dist/index.js account
node packages/cli/dist/index.js create auto --prompt "A 20s product teaser" --wait

# MCP server (stdio) — point an MCP client at this command
node packages/mcp/dist/index.js

Once published: npm i -g @vivideo/cli (gives vivideo), and npx @vivideo/mcp for the server.

Docs

Authentication & security

Keys are read from (in order): explicit option → VIVIDEO_API_KEY env → ~/.vivideo/config.json (written owner-only 0600).
The key is never printed — all output passes through secret redaction; configure stores it without echoing it.
Keys are account-scoped secrets. Keep them server-side; one per integration so a leak is revocable in isolation.

Not included (honest scope)

Cancellation — the public API has no cancel endpoint, so no cancel tool/command is offered. Failed/stuck renders are auto-refunded by the API.
Agent/chat mode — not exposed by the public API, so not in the toolchain.
Nothing here publishes to npm, provisions DNS, or deploys — those are external steps (see the final section of docs/mcp.md).

Development

bash

npm run build       # build all three packages (tsc -b)
npm run typecheck   # type-check the whole workspace
npm test            # vitest

Requires Node ≥ 18.17.

search	string	optional	Filter avatars by name.
gender	string	optional
limit	integer	optional	Max avatars to return (default 20).

language	string	optional	e.g. "English".
gender	string	optional
search	string	optional
limit	integer	optional	Max voices (default 20).

mode	string	required
model	string	optional	Required for manual mode — a model id from list_models.
duration_seconds	integer	optional
resolution	string	optional	Manual mode — one of the model's resolutions.

prompt	string	required	What the video should show or say.
duration_seconds	integer	optional	5–300, default 30.
avatar_id	string	optional	From list_avatars. Omit for a default presenter.
voice_id	string	optional	From list_voices.
brand_kit_id	string	optional	A brand_ref from list_brand_kits.
orientation	string	optional
folder_id	string	optional
name	string	optional
idempotency_key	string	optional	Optional. Reuse the same key to make a retry safe.

model	string	required	A model id from list_models, e.g. "veo31_fast".
prompt	string	required
duration_seconds	integer	optional	Must be one of the model's durations.
resolution	string	optional
aspect_ratio	string	optional
image_url	string	optional	Public https image → image-to-video.
negative_prompt	string	optional
seed	integer	optional
generate_audio	boolean	optional
style	string	optional
folder_id	string	optional
name	string	optional
idempotency_key	string	optional

io.github.egocen-vivideo/vivideo

io.github.egocen-vivideo/vivideo MCP Server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

check_configuration

check_account

list_models

list_avatars

list_voices

list_brand_kits

estimate_credits

create_auto_video

create_manual_video

get_video

wait_for_video

list_videos

render_preview