clipkit

@clipkit/mcp-server

An MCP server that exposes the Clipkit schema as tools, letting AI agents compose video projects programmatically. The Clipkit schema is the protocol — agents don't speak a custom DSL, they construct schema-valid JSON.

Install + run

npx -y @clipkit/mcp-server

Or wire it into a host like Claude Desktop:

{
  "mcpServers": {
    "clipkit": {
      "command": "npx",
      "args": ["-y", "@clipkit/mcp-server"],
      "env": {
        "CLIPKIT_API_URL": "https://clipkit.dev",
        "CLIPKIT_API_KEY": "ck_live_…"
      }
    }
  }
}

Environment

Var	Purpose
CLIPKIT_API_URL	Host for create_promo / open_in_editor links. Defaults to https://clipkit.dev. Set to http://localhost:3000 when developing against a local web app.
CLIPKIT_API_KEY	Optional dashboard key (ck_live_…, from Settings → API keys). When set, projects are owned by your team (permanent on paid plans) and sent as Authorization: Bearer. Without it, projects are anonymous and expire after 7 days.

Tools

Tool	Description
create_promo	Fastest path to a designed promo: an ordered list of scenes → composed via the pattern library → returns a shareable editor link.
create_project	Reset to a blank source. Optional dimensions, duration, fps, output format.
set_project	Replace the entire source with a validated JSON object. The primary way to build (a composition, or many elements at once).
add_element / edit_element / delete_element	Tweak a single element in an existing composition. edit_element merges a partial element (only the keys you pass change).
get_project	Return the current Clipkit source JSON.
describe_project	Plain-language summary — dimensions, timeline by track, element counts, render-time warnings. Cheaper to read than the full JSON.
validate_project	Schema validation plus render-time warnings even when valid (emoji/non-ASCII dropped by the font atlas, elements past the end, missing duration).
preview_still	Render one frame to a PNG and return it as an image — how a chat-mode agent sees its work. Free + rate-limited.
transcribe_to_captions	Transcribe a media url (or local path) into a word-timestamped caption element. Whisper in-process — no key, no upload.
open_in_editor	Validate the current project and return a link that opens it in the Clipkit editor (free).
load_project	Re-import a shared project by share id or editor URL — the round-trip for open_in_editor.
render_video	Render the current project to a finished MP4 in the cloud (paid — consumes credits, needs CLIPKIT_API_KEY).

Every mutation goes through @clipkit/protocol's validator before being applied. Invalid edits return a structured error with the offending path; valid edits are committed atomically.

Workflow

1. Compose — create_promo for a designed video, or write a full source JSON and call set_project.
2. See — preview_still to look at a frame; validate_project / describe_project for a structural read-back. Loop: edit → preview_still → fix.
3. Tweak — add_element / edit_element / delete_element for single-element changes to a large composition.
4. Deliver — open_in_editor for a free editor link (and load_project to re-import it later), or render_video for a finished MP4.

State

State is in-memory per server session. Each MCP connection gets a fresh project. There is no persistence; agents that want to save a project should call get_project and store the JSON externally.

Schema reference

See @clipkit/protocol for the full element type catalog (video, image, text, shape, audio, composition, caption) and their fields.