vidhook-mcp

An MCP (Model Context Protocol) server that lets agents generate videos through the vidhook render API. It is a thin wrapper over the existing HTTP API (POST /renders/validate, POST /renders, GET /renders/{renderId}) — it does not add a new contract, schema, or renderer.

The server speaks stdio only: an MCP client (Claude Desktop, Cursor, etc.) spawns it as a child process and communicates over stdin/stdout via JSON-RPC.

Tools

| Tool | What it does | | --- | --- | | validate | Validate a Movie definition and estimate its credit cost. Starts no render and consumes no credits. estimatedCredits equals the credits render would reserve for the same body. | | render | Start an asynchronous render. Reserves credits and returns renderId, bucketName, reservedCredits. | | get_status | Poll a render's progress with renderId + bucketName. When done and not fatalErrorEncountered, outputFile holds the result video URL. | | get_usage | Return the current credit balance (paidAvailable, freeAvailable, reserved) and recent render activity (newest first). Takes no arguments. |

All asset references in the Movie (video/image/audio src) must be URLs — vidhook does not generate assets. Compose or upload them on the agent side first.

Skill: writing correct Movie JSON

This repo also ships a Claude skill (vidhook-movie) under skills/vidhook-movie/. The split is intentional:

• MCP server = hands — it executes (validate, render, get_status, get_usage) against the API.
• Skill = brain — it teaches an agent how to author a correct Movie JSON in the first place.

skills/vidhook-movie/SKILL.md carries the workflow (always validate first → draft with a vh_test_ key → poll get_status → finalize with vh_live_), the key/environment axes, and the schema's hard spots. skills/vidhook-movie/reference/schema-cheatsheet.md is the full field-by-field reference, and skills/vidhook-movie/examples/*.json are complete, valid Movie definitions (slideshow + BGM + title, Ken Burns, transitions, and a composite of all four element types). Every example is checked against the API's parseMovie in CI (skills/vidhook-movie/examples.test.ts), so the skill cannot drift from the live schema.

The skill is delivered through the Claude Code plugin below, not through the npm package — Claude loads skills from plugins (or ~/.claude/skills/), never from node_modules.

Configuration

The server is configured only through environment variables. There is no way to pass an API key as a tool argument.

| Variable | Required | Default | Purpose | | --- | --- | --- | --- | | VIDHOOK_API_KEY | yes | — | Your vidhook API key. Missing/empty fails startup (fail-closed). | | VIDHOOK_API_BASE_URL | no | https://api.vidhook.app | API base URL. |

Two independent axes

Watermarking and the target environment are separate and must not be confused:

• Key type (VIDHOOK_API_KEY prefix) → watermark & billing.
  • vh_test_… → free tier, watermarked output (use for drafts/iteration).
  • vh_live_… → paid, clean output (use for final renders).
• Base URL (VIDHOOK_API_BASE_URL) → environment.
  • e.g. https://api.vidhook.app (production) vs. a staging base URL.

A vh_test_ key against production still watermarks; the base URL only changes which environment you talk to, never whether the output is watermarked.

Installing in MCP clients

The server is published to npm and runs via npx, so most clients need no separate install step — just point them at npx -y vidhook-mcp and set VIDHOOK_API_KEY. Requires Node.js ≥ 20. Use a vh_test_… key while wiring things up (free, watermarked); swap in vh_live_… for clean output once it works.

Claude Code (recommended): skill + MCP in one

Claude Code can install this repo as a plugin, which bundles both the vidhook-movie skill (the brain) and the MCP server declaration (the hands) in a single step. This is the only way Claude auto-loads the skill — it is not picked up from node_modules.

/plugin marketplace add https://github.com/vidhook/vidhook-mcp
/plugin install vidhook@vidhook

The plugin prompts you for your vidhook API key when it's enabled (masked input, stored in your system keychain — never written to settings.json). Verify with /plugin (skill listed) and claude mcp list (server vidhook registered).

To add just the tools (no skill) from the CLI instead:

claude mcp add vidhook -e VIDHOOK_API_KEY=vh_test_your_key_here -- npx -y vidhook-mcp

(-e sets the env var, everything after -- is the launch command.) Scoped to the current project by default; add --scope user for all projects, or --scope project for a shared .mcp.json.

Other MCP clients

Most clients use the same mcpServers shape. Add this entry to the client's MCP config file, then restart the client:

{
  "mcpServers": {
    "vidhook": {
      "command": "npx",
      "args": ["-y", "vidhook-mcp"],
      "env": { "VIDHOOK_API_KEY": "vh_test_your_key_here" }
    }
  }
}

The config file location differs per client:

| Client | Config file | Notes | | --- | --- | --- | | Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) · %APPDATA%\Claude\claude_desktop_config.json (Windows) | Settings → Developer → Edit Config | | Cursor | .cursor/mcp.json (project) · ~/.cursor/mcp.json (global) | | | Windsurf | ~/.codeium/windsurf/mcp_config.json | Cascade → MCP settings → manage | | VS Code (Copilot) | .vscode/mcp.json (workspace) | Top-level key is servers, not mcpServers |

VS Code can also add it from the command line: code --add-mcp '{"name":"vidhook","command":"npx","args":["-y","vidhook-mcp"],"env":{"VIDHOOK_API_KEY":"vh_test_your_key_here"}}'

npx -y vidhook-mcp fetches and runs the published package. If you install it globally (npm i -g vidhook-mcp), set "command": "vidhook-mcp" with no args instead.

Local development

Clone this repo and run the server directly from source:

mise run setup        # install deps (or: pnpm install)
pnpm dev              # stdio server (tsx src/index.ts)
pnpm build            # bundle to dist/index.js (tsup)

Tests

pnpm test             # unit (HTTP boundary stubbed) + skill example structure
pnpm test:e2e         # validate every skill example against the live API (needs VIDHOOK_API_KEY)

The test:e2e run is the schema drift-check: each skills/vidhook-movie/examples/*.json is sent to the live /renders/validate, so the examples cannot go stale against the real Movie schema.

Local smoke test

e2e/smoke.ts runs validate → render → get_status → get_usage once against a real API to leave an end-to-end trace:

VIDHOOK_API_KEY=vh_test_... VIDHOOK_API_BASE_URL=https://staging-api.vidhook.app \
  pnpm exec tsx e2e/smoke.ts

It prints only the key prefix (never the full key).