MCP server#

@clipkit/mcp-server exposes Clipkit to any MCP-compatible host — Claude Desktop, Cursor, Zed, custom agents — so the model authors video projects directly through tool calls instead of generating JSON in chat.

The server is a thin wrapper around @clipkit/protocol. Every mutation runs through the same validator the runtime uses, so an agent can never advance the project into a state the renderer would reject.

Install#

The server runs over stdio via npx — no clone, no build:

npx -y @clipkit/mcp-server

You won't normally invoke it directly. Configure your MCP host to launch it.

Claude Desktop#

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "clipkit": {
      "command": "npx",
      "args": ["-y", "@clipkit/mcp-server"]
    }
  }
}

Restart Claude Desktop. The Clipkit tools appear in the tools menu; the clipkit:// resources appear under the Resources picker.

Cursor / Zed / other hosts#

Use the same command + args pair. Any MCP host that speaks the stdio transport will work.

Remote connector (hosted)#

Besides running locally over stdio, Clipkit is available as a hosted remote connector:

https://clipkit.dev/mcp

It speaks the standard Streamable HTTP transport, runs sessionless, and is open — no sign-in or OAuth. Any MCP-compatible client adds it by URL. Because the server is sessionless, each project has a project_id (returned by create_project / set_project / create_promo / load_project); pass it to subsequent tools. (Locally over stdio you can omit project_id — there's a single implicit project.)

Free, anonymous authoring needs no key. A CLIPKIT_API_KEY (Settings → API keys) is only required for the paid render_video path; creating projects and stills are free.

transcribe_to_captions is local (stdio) only. It runs Whisper in a child process and needs ffmpeg on the host, so it is not exposed on the hosted connector. (Hosted speech-to-text — via the render service or a hosted STT endpoint — is on the roadmap; figure out later.) Transcribe over a local stdio server, or use the hosted open_in_editor / render_video paths.

Claude#

Settings → Connectors → Add custom connector, and paste https://clipkit.dev/mcp. (Once Clipkit is in the Connectors Directory you'll be able to add it from the picker directly.)

OpenAI Codex#

In ~/.codex/config.toml:

[mcp_servers.clipkit]
url = "https://clipkit.dev/mcp"

Gemini CLI#

Use the httpUrl key — not url (which selects the deprecated SSE transport and fails silently):

{ "mcpServers": { "clipkit": { "httpUrl": "https://clipkit.dev/mcp" } } }

Cursor#

In mcp.json:

{ "mcpServers": { "clipkit": { "url": "https://clipkit.dev/mcp" } } }

Cline / other clients#

Add a remote server with URL https://clipkit.dev/mcp and pick the Streamable HTTP transport (not SSE).

Tools#

Tool	Purpose
`read_docs`	Return a canonical doc (authoring guide / protocol / brand) as text.
`get_schema`	Return the JSON Schema for a Source, or one element type's fields.
`create_project`	Start a new blank project (optional dimensions/duration). Returns its `project_id`.
`set_project`	Replace the entire Source with a validated JSON object. Returns its `project_id`.
`get_project`	Return the current Source as JSON.
`describe_project`	Plain-language structural summary + render-time warnings.
`add_element`	Append one element (optionally into a group via `parent_id`).
`edit_element`	Merge changed fields into one element by `id` (anywhere in the tree, incl. nested).
`delete_element`	Delete one element by `id` (anywhere in the tree).
`validate_project`	Schema validation + render-time warnings.
`preview_still`	Render one frame to a PNG so the agent can SEE the result (free).
`transcribe_to_captions`	Speech-to-text a media file into a timed `caption` element. Local (stdio) only — not on the hosted connector (see note above).
`create_promo`	Assemble a designed promo from prebuilt scenes; returns an editor link.
`open_in_editor`	Create a share link that opens the project in the web editor.
`load_project`	Import a shared project by id / editor URL.
`render_video`	Render a finished MP4 in the cloud (paid; needs `CLIPKIT_API_KEY`).

Every stateful tool also takes an optional project_id (see Remote connector). Validation is non-negotiable — every mutation hits @clipkit/protocol before being applied. Invalid edits return a structured error with the offending JSON path; valid edits commit atomically, so the agent never observes a half-applied project.

Resources#

The server publishes the canonical Clipkit reference docs as MCP resources, so any host that supports resource attachment can pull them into the model's context without web search.

URI	Contents
`clipkit://docs/agents.md`	The authoring guide (`AGENTS.md`). Patterns, recipes, conventions.
`clipkit://docs/protocol.md`	The normative protocol spec (`PROTOCOL.md`).
`clipkit://docs/brand.md`	Brand reference (`BRAND.md`). Voice, colors, typography.

Resources are embedded at the server's build time — the bytes you load are the bytes that shipped with the version of the package you installed, never a live fetch.

Workflow#

A typical agent loop:

create_project — start with the right dimensions and duration.
add_element once per element (text, shape, image, video, audio, caption), or set_project to author the whole composition at once.
edit_element to tune properties iteratively (color, position, font_size).
preview_still to SEE a frame; validate_project to confirm before exporting.
get_project to retrieve the final JSON.
open_in_editor for an editor link, or render_video for a finished MP4.

State#

Local (stdio): state is in-memory per server session — one implicit project per process, no persistence. project_id is optional.

Hosted (remote connector): the server is sessionless. Each project is persisted, keyed by the project_id returned from create_project / set_project, so any instance can serve any request — pass project_id to subsequent tools. Hosted projects are scratch state and expire; the durable artifacts are the editor link (open_in_editor) and renders (render_video).

Either way, to save a project durably call get_project and store the JSON, or use open_in_editor for a link.

Schema reference#

See the protocol spec for the full element type catalog (video, image, text, shape, audio, group, caption, particles) and every field on every element.

License#

Apache-2.0.