Clueso MCP integration
Design connector, available on Zeplik
Clueso MCP is available as an integration on Zeplik, the AI assistant that works across every model in one chat. Connect Clueso MCP and Zeplik can act on your design for you: Create and edit Clueso product videos, documentation articles, clips, voiceovers, captions, animations, and exports through Clueso's hosted MCP. You stay in the conversation while the assistant does the work in Clueso MCP directly.
Zeplik exposes 15 read actions and 38 write actions for Clueso MCP. Read actions run automatically; write actions stay off until you enable write access in Settings, so nothing is changed in Clueso MCP without your consent.
Try Clueso MCP on Zeplik
Pick a prompt to open it in the Zeplik app. If you are not signed in yet, your prompt is waiting for you the moment you do.
What Zeplik can do with Clueso MCP
Read from Clueso MCP (15)
Runs automatically in any conversation.
Check uploads
Fetch all files the user uploaded via the hosted upload page. Returns one mcp_upload_id per file — pass each to the appropriate tool (add_clips, add_article_media, etc.). Call this once after the user confirms they are done uploading; the token covers all files they dropped on the page.
Extract audio
The editor's "Extract Audio": a clip's own audio — the recording's sound on a video clip, or its generated voiceover — becomes a separate audio track (returns music_id), and the clip goes silent. - The track starts where the clip starts and plays at normal speed. Shape it with update_audio (trim music_start_time / music_end_time, move guide_start_time, fade, volume); analyze_audio(file_url=<its src from get_project.audio_tracks>) reads it. - The track stays in sync through later edits — yours, and voiceover landing on other clips: clips before it moving or resizing, and cuts inside it (split_clip + remove_clip of a part re-cuts the track to what's left; removing a middle part splits it in two). Removing every clip it played under leaves the track where it was; a track you moved or trimmed out of sync stays where you put it. - While extracted, the clip's voiceover is locked: voiceover_batch skips it, and an update_clips voiceover_volume on it is not applied (that entry comes back as an error). - restore: true gives the clip its own audio back at 100%. The extracted track stays — remove it with remove_from_project(target='audio') if unwanted. Keep-the-audio, swap-the-visual (e.g. a webinar segment over stock footage): 1. Cut the recording to the segment(s) with split_clip + remove_clip (before or after extracting). 2. extract_audio on the clip(s). 3. Cover, don't delete: add_elements a full-canvas, fully opaque visual on that clip for its whole duration — a stock video (find) with volume 0, an image, or a background shape + text. The recording keeps playing underneath unseen, and the clip's captions still follow the extracted audio's words. Errors if the clip is already extracted, has no audio (a slide with no generated voiceover), or speech is generating on it. Concurrency: whole-project mutation — serialize; do not run in parallel with other mutations on the same project_id.
Find
Find any resource in Clueso by type, optionally filtered by name or exact id. One tool for listing and searching across the workspace. type: • projects | folders | tags | clueprints | workspaces (tags = the workspace's project tags, each with `color` and `project_count`. Apply them with update_project. Each project result carries its `tags` (names); filter projects by them with `tags` + `tag_match`.) • backgrounds | voices | fonts | image_gen_style_packs | code_style_packs | element_components | animations | avatars • clip_templates — one-clip intro/outro/chapter-break covers (a clueprint is a whole video). Replies in sections, not items: `defaults` {intro, outro}, `folders` + `templates` (this workspace), `library_templates` (Clueso's; unnamed, so refer to one by `template_id`). `source`: 'defaults' | 'org' | 'library' | 'all' (default); `clip_label`: intro | outro | chapter break | others; `folder_id` narrows the workspace's templates. Insert one with add_clips(kind='template'). (voices carry `gender`, `tags`, `accent`, `engine` and a `description` of tone, age, accent and use (the catalog's own, else ElevenLabs' labels: "calm, middle aged, american, male — good for narration"; a voice with neither has none), which is the field actually worth choosing on. `tags` is a small closed vocabulary, so it groups voices rather than telling them apart. Choose deliberately: voiceover is the film's clock, and regenerating speech later rescales the clip and every element time and keyframe with it.) • images | videos | music | sfx — media; each result carries a `source` ('org' = your saved-media library, 'stock' = a stock/curated provider). Scope with `source`, pick the library with `provider` (see below). Stock results are a short described shortlist — pick the best fit and use its `src`. Stock video results also carry `safe_src` and a `video_files` tier list with one entry marked `recommended` — use `safe_src` (or the recommended tier) in add_elements; tiers above 1080p can exceed its ~200MB source cap and fail. For a Freesound music/sfx result, `src` is an OPAQUE handle (not a playable URL) — pass it straight to add_audio and the original is fetched + hosted by Clueso server-side; `detail:'full'` adds a `preview_url` so you can tell what it sounds like. • brand_kits | icons (brand_kits = this workspace's brand kits, default first, each with `is_default`, `source_domain`, `accent`, `title_font`, `logo_count`, `icon_library`, `updated_at` and `edit_url` (where the user edits it). Nothing is implicit: pass a kit's id as get_design_guide's brand_kit_id to read it, or as create_project / update_project brand_kit_id to build a project with it, so one project can use kit A and another kit B. `detail:'full'` returns each whole kit as JSON: palette by role, logos (id, url, kind, for_background, aspect, sample), fonts (family, role, weights, the font_setting to pass), icons, captions, voices, guidelines, company knowledge, reference images. `logo_count` counts the brand's real logos; generated samples are `sample_logo_count`.) (icons = icon names in the brand kit's icon library for `query`, drawn the kit's way (style, stroke, color), with the icons the kit pins for that concept first. A kit with its own uploaded icon set: use its own icons first (get_design_guide 'brand.icons'); the library is the fallback for what they do not cover, and the reply says so. The kit is project_id's (else the workspace default) or brand_kit_id's. The reply names the set and carries `usage`, the exact line to draw one. One icon library and one style per video: an icon missing from the kit's set → search the set again with other words; never switch sets. `library` searches another set, only for a video that uses no other. `detail:'full'` adds each icon's `src`, an SVG in the kit's color for add_elements element_type 'image'.) (fonts = the typefaces THIS WORKSPACE has uploaded as brand fonts (add one with upload_file purpose: 'font'), each with `id` and `name`. Pass a returned `name` as a text element's `font_setting.font` — that is the whole contract; you never pass the url. This list is the ONLY way to know which non-Google families actually exist here: a font_setting naming a family in neither this list nor Google Fonts silently renders Inter, with no error and a confident-looking `layout.text_width_px` measured against the wrong face. Check here before building a layout on a brand typeface.) (animations = reusable animations: this workspace's (tier 'org'), Clueso's official ones and the community library, ranked by usage with featured first. By default each row is compact: `ref`, `title`, `entries` (the names of its placeable entries), `scope`, `tier`, `rev` (latest revision), plus `project_id`, `featured` and `dependency_update_available` when they apply. `detail:'full'` returns every field instead: entry titles and parts, `latest_rev`, `live_rev`, `uses` and `dependency_updates` [{animation, pinned_rev, latest_rev}] (re-pin with animation.update_dependents('<that animation>') in run_script). Place one with add_elements(element_type='animation', type_data: {animation: ref, entry}); read its code with read_animation. Filter with `tier`. New animations are saved to their video's project: pass `project_id` to include that project's, and a `query` also searches every other project's (each such row carries its `project_id`), so another film's kit can be found and imported by its ref.) (image_gen_style_packs = generation style presets for generate_media kind='image' style_id, each with `ready`; code_style_packs = looks for animation code, each with its `examples` count; `id` + `query` (what you will animate) reads one: its style_prompt and closest examples (code, description, params) whole, to match when you write the code; element_components = saved components (e.g. animations) from THIS WORKSPACE only — there is no community library for components (unlike clueprints); each reports param_keys. Insert one AS-IS with add_elements(component_id=...), or generate a variant from it with base_component_id.) (avatars = AI presenter looks for add_elements element_type='avatar' — pass the id as type_data.avatarId. No query lists one default look per character; a query matches character and look names and returns every matching look. Each carries `styles`, `engine`, `credits_per_minute` and a `preview_image`.) Filters (all optional): • query — for stock media it's the search phrase (real semantic search for provider='clueso'; provider keyword search otherwise). For clueprints a query runs a relevance-ranked search across your workspace + the global community library (search_summary, relevance_reason, tags, is_community, fork_count). For everything else it's a case-insensitive name substring. • provider — which stock library to search (ONE call, no merging). Choose by strength: images → 'pexels' (default; realistic photography) or 'pixabay' (illustrations, vectors, icons, clip-art — set image_type) videos → 'pexels' (default; real-world footage) or 'pixabay' (motion graphics — set video_type='animation') music → 'clueso' (default; our curated, brand-safe library with the best descriptions/search) or 'freesound' (niche/genre tracks) sfx → 'freesound' (default; vast sound-effect library) or 'clueso' (curated sfx) music/sfx options for the user → search BOTH ('clueso' and 'freesound', same query and filters, in parallel) and offer the best 3-5 across them; picking one yourself → 'clueso' first, 'freesound' when it has no fit • image_type — images + provider='pixabay': 'photo' | 'illustration' | 'vector' • video_type — videos + provider='pixabay': 'film' | 'animation' • id — exact id; returns just that one record (any type; for music/sfx a stock result's id or src, looked up directly) • source — media only: 'org' | 'stock' | 'all' (default = org + stock). Under 'all', stock is appended only when a query is given. sfx is stock only. • folder_id — projects + saved media (images/videos/music): restrict to a folder; projects: 'root' = outside every folder • engine / language — voices only • tags — voices: descriptive words ('calm', 'british', 'narration'); any one matches. `query` matches voice NAMES only, so a description goes here. A query or tags also searches the shared voice catalog (each row's `source`: 'org' or 'catalog'); without either only this workspace's voices list. projects: keep projects carrying the named tags (names match ignoring case; list them with find(type='tags')). • tag_match — projects only: 'any' (default) = at least one of the tags, 'all' = every one, same as the home page's Tags filter. A name the workspace doesn't have matches nothing. • creator_id / mine_only — clueprints only • orientation — stock images/videos: 'landscape' | 'portrait' | 'square' • color — stock images: a color name/hex, e.g. 'blue' • size — stock videos: 'large' | 'medium' | 'small' • min_duration / max_duration — stock videos + freesound audio: length bounds in seconds • page / limit — paging for large sets (projects, components, clueprints, animations — a clueprint list is sliced to the limit with no marker when more exist, so page through rather than assuming the first page is everything). `limit` caps every type, stock media included (a stock shortlist has no further pages); a capped reply says how many it left out. • music/sfx filters — only for what the brief actually says; `query` stays the main signal (2-5 words for how it SOUNDS: "warm acoustic upbeat", "fast air whoosh", never the video's topic). `mood` / `genre` / `energy` rank (a miss is never hidden); `vocals:false`, `bpm_min` / `bpm_max`, `avoid` and `sfx_type` filter (a track with no label for it still passes). Under voiceover pass vocals:false. `similar_to` = an earlier result's id (a Freesound src also works; a clueso library src link doesn't) → sounds like it, instead of the text search (e.g. when the user rejects a pick); it takes none of the other filters. Music/sfx results carry the matching labels (mood, genre, energy 1-5, vocals none|wordless|lyrics, sfx_type, bpm) — choose on them and the description, never the name alone. • detail — animations, voices, music, sfx, fonts, brand_kits, icons: 'compact' (default; the essentials, 8 rows unless you pass limit; fonts and brand_kits list them all) or 'full' (every field: preview urls, thumbnails, attribution, rhythm detail, full descriptions; a brand kit's every section) Returns { type, count, items: [{ id, name, type, ... }] }, plus total and has_more for projects and folders. Feed the returned id straight into the consuming tool (set_voice, update_clips background, generate_media style_id, add_audio src, use_clueprint, etc.). Any `duration` on a returned item is in SECONDS — pass it straight to add_audio's source_duration.
Get article
Get the article content as markdown. Screenshots appear as <SCREENSHOT {id}> placeholders. Returns the markdown text and a list of screenshot IDs.
Get clip
Read one clip: its elements (positions/sizes in canvas pixels), voiceover (text, voice, duration, voiceover_volume), background and transition. Pass `render` to also get a PNG of the frame. ASK FOR WHAT YOU NEED. A full read is large — on a dense clip the per-word voiceover array and the element type_data blobs dominate it, and repeated full reads are the main way a long session runs out of context. `select` returns exactly the parts you name: select: ['elements.x','elements.y','elements.width','elements.height'] → geometry only, to fix a layout select: ['elements.name','elements.start_time','elements.end_time'] → a timing pass select: ['voiceover_words'] → word timings only, to sync visuals to narration select: ['elements.textdata','voiceover_words'] → rewrite copy against the VO select: ['elements'] → whole element rows, no words select: ['groups'] → group rows only, to get a group_id for update_groups select: [] → no JSON at all (pair with render for the PNG alone — smallest read) (omit select) → everything; fine for a first look, expensive to repeat `render` is the other output, and it is separate from `select`: `select` shapes the JSON, `render` produces a PNG. render: {} → the frame at t=0 render: { timestamps: 2.5 } → the frame 2.5s into the clip render: { timestamps: [0.5, 2, 4] } → those three moments as ONE labelled grid render: { timestamps: [...], layout:'separate'} → the same moments as full-size images (~4x the tokens) render: { save: true } → also uploads the frame and returns presigned_url render: { element_id: 'e1' } → just that animation, cropped, at four moments (a fast check) render: { filmstrip: true } → the whole clip, every element, as 12 frames in one image with a timeline of cues, actions and element starts/ends render: { animation: '@org/cast', entry: 'maya' } → that entry alone on this clip, nothing placed or saved render: { preview: '<token>' } → an edit_animation dry run, cropped, at four moments (a render of one animation also returns { warnings }: a glow cut at its box, text off its frame, frames near the limits) render: { element_id: 'e1', actions: [{name:'wave', start: 1}], cues: {reveal: 2} } → try settings, tracks, actions or cues without saving render: { max_width: 1280 } → a sharper frame when you must read small print select: [], render: {} → the PNG alone, no JSON (the default for a render of one animation) select: ['elements'], render: {} → element rows AND the frame A single frame renders 960px wide by default — legible for this design system and about half the tokens of a 1280 frame. A GRID defaults to 1280, because that is the width of the whole grid and a third of 960 would leave each cell unreadable. Either way `max_width` caps the image you get back; raise it only to read genuinely small print. For a render of one animation (element_id, animation + entry, preview) it sets the resolution the canvas is drawn at before the crop: each cropped cell of the sheet is at most 360px wide whatever you pass, so a higher max_width sharpens a small element but does not enlarge the sheet. To look closer, use layout:'separate' (full-size crops) or render the clip frame without element_id. Omitting `render` renders nothing. `timestamps`, `layout` and `save` live inside it because they only mean anything for a render — there is no way to ask for them without asking for the image. `element_ids` is the other axis: it picks WHICH element rows come back, independently of `select`. Combine them for the leanest read — e.g. element_ids: ['el_9'], select: ['elements.x','elements.y']. Element shape: universal wrapper fields (id, element_type, name, x, y, width, height, start_time, end_time, rotation) plus type-specific data (textdata/shapedata/imagedata/videodata/zoomdata) plus an optional `keyframes` array when animated. Keyframes come back in the same flat wire shape add_elements takes — { timestamp, positionX?, positionY?, width?, height?, interpolation? } in canvas pixels — so you can round-trip read → edit → update_elements without reshaping. An animation element that comes from an animation carries an `animation` block: { ref, entry, rev, live, updateAvailable, behind?, dependencyUpdates?, manifest: { params, actions: [{name, args, default_duration}], cues, presets, parts } }. That manifest is the vocabulary for update_elements' param_tracks / actions / cues, e.g. update_elements({updates:[{element_id, type_data:{cues:[{op:'set', key, t}]}}]}) — plan against it, not against the code. `behind: {rev, latest}` means the element still shows an older revision than the animation's latest passing one (placed elements stay on their revision until moved, unless they follow Live); `dependencyUpdates: [{animation, pinnedRev, latestRev, through?}]` means its animation imports, directly or through others, an older revision of another animation (`through` names the older one whose chain also re-pins it). The top-level `warnings` then says how many elements are affected and names the call that moves them: animation.update_uses('<animation>', {project}) or animation.update_dependents('<dependency>', {project}) in run_script. Clip-level fields include `transition` (the current transition object — sibling of the update_clips `transition` arg; null if none) and `voiceover_words` (per-word timestamps, `{word, start, end, punctuated_word}` with start/end in SECONDS; null on clips with no transcription).
Get clueprint
Fetch clueprint data. Use `include` to control how much you pull back: - include="metadata": just the clueprint's name/description/tags/visibility/thumbnail. - include="tree": metadata + the full file tree (path, mime_type, and size per entry). Call this first when exploring an unfamiliar clueprint. - include="files": the contents of the files listed in `file_paths` (no metadata — call include='tree' first if you also need metadata). Text inline, binary as presigned GET URLs. - include="all": metadata + the file tree + the contents of every file in the clueprint (use sparingly on large clueprints). Every read is logged for the workspace's recents. Pass use=true ONCE, when you start building a project from it: that counts the use (the clueprint's use count, apply analytics); add project_id when the project already exists. Building from it: Brand kit vs clueprint: the brand kit sets WHO (logos, palette roles, fonts, icons, company facts, brand guidelines); the clueprint sets THE FORMAT (structure and layouts, pacing, motion, transitions, script and voiceover style, music, caption style and animation unless the kit has its own caption style, effects). With both, the kit wins on identity and the clueprint on format; the user's explicit ask beats both. Re-skin the clueprint's literal colors, fonts and logos to the project's kit roles (pick the logo variant by scene background). A community clueprint or another workspace's is always re-skinned, never shipping another company's logo; only this workspace's own clueprint with brand_locked: true keeps its colors, fonts and logos. The reply's `brand` says whether this clueprint is brand_locked for this workspace; pass clueprint_id with project_id to get_design_guide for the kit to re-skin with.
Get comments
Read the review comments on a project — the other half of `add_comment`, which could post but never read. Comments are how a human reviewer tells you what is wrong with a video: a note pinned to a clip and a moment inside it. Read them before an editing pass so you act on what was actually asked for, and read them again after a build if a reviewer has seen it. Threads come back nested: each top-level comment carries its `replies`. Reply into a thread with add_comment(parent_comment_id=...) rather than posting a new top-level note — a reviewer reading their own thread is how they see that their point was handled. Resolved threads are hidden by default, so a plain read is "what still needs attention".
Get design guide
Clueso's design guide, animation guide and animation stdlib. Ask for everything you need in ONE call. Each select entry is a section path or plain words; words search the design guide, animation guide and stdlib together and return the best few, each labelled with the path that selects it exactly. get_design_guide({select: ['gist', 'styles.kinetic-type', 'motion.*', 'animation.contract', 'stagger from the centre']}) Paths: 'gist' (the design gist and its contents; also what no arguments returns); design sections ('motion.camera', 'x.*' with its children, '*' for all); 'animation.gist' (the animation guide's gist and contents), 'animation' (its core) or 'animation.<path>'; 'stdlib' (its modules), 'stdlib.<module>' or 'stdlib.<member>' ('stdlib.native.tween'). Start with select ['gist', 'animation.gist', ...] for both gists. One header per entry; anything past the size budget is listed by path for your next call. (topic/query still work.) Brand: pass project_id (or brand_kit_id) and the reply starts with a short 'brand' section: the brand kit's palette by role, each font role's exact font_setting, its logos (id, kind, for_background, aspect, url) and its guidelines. Follow it by default. 'brand.<section>' returns one section in full as JSON with its edit link: overview, company (product knowledge), palette, logos, fonts, reference_images, guidelines, icons, captions, voices; 'brand.*' for all. Use an item by reference: a logo → add_elements element_type 'image' with src = that logo's url (match for_background to what is behind it; never recolor); a color role → its hex (palette.accent); a font role → its font_setting. List kits with find(type='brand_kits'); set a project's kit with update_project brand_kit_id. Building from a clueprint: pass its clueprint_id too, and the brand section says which of the two decides what (the kit: identity; the clueprint: format).
Get element schema
Return the schema for an element type's type_data, as TypeScript declarations. Call this before add_elements / update_elements when you don't already know the field shape for the element_type you're placing. By default it is compact: every field with its type and a one-line note, plus the keyframable list. Ask about specific properties with `fields: ['background_setting']` or `query: 'pill background'` — those come back with their full notes, default and an example; `detail: 'full'` returns everything, including the keyframe rules. Inside run_script it is a function like any tool: get_element_schema({element_type: 'text', query: 'line height'}) looks a property up mid-script. Fields are listed in camelCase, the names get_clip returns. Where the tool descriptions write one in snake_case (font_setting, animation_setting), the field says so — `(= font_setting)` on fontSetting — and either spelling is accepted. Pass element_type='group' for the GROUP surface instead — what a group is, how its pivot works, and the nine properties it can animate.
Get embed
Get a project's embeddable video player: `embed_url` (permanent) and `embed_code` (a ready-to-paste <iframe>, the same snippet the editor's Share → Embed copies). Use it to put a Clueso video in a website, help center or LMS lesson. Returns { project_id, published, embed_url?, embed_code?, latest_publish? }. • published=false — the project has never been published as an embed. Call export_project(project_id, destination="embed"), tell the user it has started and stop; get_export(export_id) returns the embed_url once it is done and the user asks. • published=true — the URL is live. After editing the project, re-publish with export_project(destination="embed"): the video behind the SAME URL is replaced, so every page embedding it updates without changing the embed code. • latest_publish — the most recent embed publish { export_id, status, progress, requested_at, finished_at }. While it is queued/inprogress, embed_url still serves the previous version.
Get export
Read a project's video export: its status and, once done, its link. Call it when the user asks for the link or the status, not to wait on an export you just started (the user gets that in the editor's Exports tab, so start it, say so, and stop). Pass exactly one of `export_id` (the one export_project returned) or `project_id` (that project's most recently REQUESTED export, which may still be in progress). Returns { export_id, project_id, status, progress, requested_at, finished_at? }. `status` is queued, waitlisted or pending (not started yet), inprogress (`progress` is 0-100), completed, failed, or stalled (stuck for hours; start a new export). The call holds open until the export completes, fails or stalls, or `wait_seconds` runs out, then returns the current status. Don't call it in a loop: if it is still rendering, tell the user it is in progress and stop. With project_id, a project that has never been exported returns status `not_exported` straight away (nothing to read): call export_project(project_id) if the user wants one. Once completed, the reply carries `download_url`: a direct, time-limited link (1 hour, see `expires_at`) that downloads the file named after the project, e.g. "Product tour.mp4" (`filename`). Calling get_export again mints a fresh link. An embed publish (export_project with destination="embed") also completes with `embed_url` (permanent) and `embed_code` (a ready-to-paste <iframe>), alongside its download_url.
Get project
Get a summary of a project: canvas dimensions, per-clip summary (ids, indices, durations, element counts, voiceover_volume), and `audio_tracks` — every music/SFX entry on the project flattened to the same wire shape `add_audio` accepts (id, src, name, source_duration, guide_start_time/end_time, music_start_time/end_time, volume, loop, fade_in, fade_out). To copy an audio track to another project: read it from `audio_tracks` here and feed the same fields to `add_audio` on the target project. `brand_kit` is {id, name, follows_default}: the brand kit this project is built with (follows_default true: the workspace default kit; null when the workspace has none); get_design_guide({project_id}) returns its colors, fonts, logos and guidelines. `clueprint` is {id, name} when the project was made from a clueprint (null otherwise): keep its format (layouts, pacing, motion, captions) in later edits; get_design_guide({project_id}) includes its rules. Call this to understand what's in the project before making changes. A clip whose voiceover this server is still generating carries `duration_pending: true` (with a top-level `durations_pending` note): its duration is the old value until the audio lands. get_clip says the same as `duration_pending` on any read that shows timings. Pass `render` to check the whole film in ONE image instead of the summary: {seams: true} every cut, {clips: true} one frame per clip (its middle; {clips: {at: 'start'|'middle'|'end'|<seconds>}} for another moment), {at: [film seconds]}. get_clip's filmstrip {seam: true} zooms into one cut.
and 3 more.
Act in Clueso MCP (38)
Runs only after you enable write access.
Add article media
Add a screenshot or GIF to the article. Returns a screenshot_id to place in the article via update_article using `<SCREENSHOT screenshot_id>`. - kind="image": one of `timestamp` (capture a frame from the project's base video), `mcp_upload_id` (an uploaded image: `mup_…` from upload_file, or a Clueso upload_id) or `source_url` (an image URL, e.g. one generate_media returned). - kind="gif": pass `timestamp` (start) and `duration` (seconds). Captures a short GIF clip from the base video. Requires the project to have a video clip.
Add audio
Add a music track or sound effect that plays as a project-level audio layer over all clips. Does NOT consume a clip slot. Use this for background music or a soundtrack that should play under the existing timeline. (For inserting an audio file as its own sequential clip with auto-transcription, use add_clips(kind='video') with an audio mime_type instead.) - type="music": requires src. `src` is the `src` from a find(type='music') result (pass with its name and duration as source_duration), or an upload: an mcp_upload_id (`mup_`) from upload_file or a Clueso upload_id, whose name and duration are filled in for you. For a Freesound result the `src` is an opaque handle; pass it through unchanged and Clueso downloads + hosts the original server-side (do not try to fetch it yourself). Anything not from find has its duration probed. Optional: guide_start_time, guide_end_time, music_start_time, music_end_time (trim the source track), volume, loop, fade_in, fade_out. A user's own upload is also saved to the project's media panel (saved_to_media_panel). - type="sfx": pass the `src`, `name`, and `source_duration` from a find(type='sfx') result (or an upload as `src`), plus guide_start_time (Freesound `src` is an opaque handle, resolved server-side just like music). Optional: volume. (Legacy: a fixed-library `sfx_key` like 'whoosh' still works instead of src.) Concurrency: whole-project mutation (conflict domain: the entire project) — serialize; do not run in parallel with ANY other mutation on the same project_id (including element/voiceover edits). Size your clips BEFORE calling add_audio, or pass guide_end_time explicitly — the default ('end of project') is captured at call time and will NOT auto-extend if clips are added or resized afterwards.
Add clips
Create new clips on a project. One tool, four sources: - kind="blank": empty slide clips you'll populate with add_elements / generate_media. Pass `clips: [{title?, duration?}, ...]`. Note: create_project already creates clip 0; calling with N blank entries gives N+1 clips total. - kind="pptx": extract slides from an uploaded .ppt/.pptx. Pass `mcp_upload_id` (from upload_file), optional `slide_indices`. Each slide becomes a slide_clip with native text/image/shape elements pre-populated. - kind="video": cut clips from an uploaded video/audio. Pass `mcp_upload_id` and optionally `mime_type` (default video/mp4), `title`, `voiceover_text`, `cuts: [{start_seconds, end_seconds, heading?}]`, `auto_elements`. Without `cuts` the whole upload becomes one clip. Pipeline (download → transcribe → insert) runs in the background; subsequent calls on the same upload hit a 24h cache and return synchronously. (To overlay a video ONTO an existing clip — picture-in-picture, b-roll, background loop — rather than insert it as its own clip, use add_elements(element_type='video') instead.) - Re-cut clips already on the timeline: pass `source_start_clip_id`, `source_end_clip_id` (a run of video clips from one recording, inclusive) and `cuts` instead of an upload. The run is replaced in place by one clip per cut; cut seconds are on the run's own clock (0 = start of the first clip). Recording cut out between the clips counts back in, so a cut across it restores that footage (`restored_gap_seconds`). - kind="template": one clip from a clip template (find(type='clip_templates')). Pass `template_id` and `text_overrides` (strings for the template's text elements in document order; a missing or empty one keeps the placeholder — fill them with the user's words). `after_clip_id` is REQUIRED: ask the user where it goes, never guess. Insert only; a template whose aspect ratio differs from the project is refused (`aspect_mismatch` — pick another). The clip inherits the project's voice. All variants accept `after_clip_id` to control insertion position; appends at end if omitted (except kind="template"). Concurrency: whole-project mutation (conflict domain: the entire project) — serialize. Do not run it in parallel with ANY other mutation on the same project_id, including element/voiceover edits; run them one at a time. (Mutations to different projects run in parallel freely.)
Add comment
Post a review comment on a project, attributed to "Clueso AI". Use this to leave feedback, suggestions, or notes — either at the project level (no clip_id) or pinned to a specific clip with an optional timestamp inside that clip. Pass `parent_comment_id` to REPLY to an existing comment rather than open a new thread. Read what is already there with `get_comments` first: answering a reviewer in their own thread is what makes the note resolvable, where a fresh top-level comment just adds noise.
Add elements
Add many elements across one or more clips in a single tool call. Replaces the per-element tool — always batch. SEND LESS. Most batches repeat themselves — the same clip_index, element_type, font_setting, alignment or gradientSetting on every item. Hoist those into `defaults` and send them once; each item then carries only what differs, and overrides any key it sets (type_data merges one level). On a 20-30 element batch this typically cuts the call by a quarter to a half. `returning` shapes the response the way `select` shapes a get_clip read. defaults: { clip_index: 2, element_type: 'text', type_data: { font_setting: { font: 'Inter', weight: '600' }, alignment: 'center' } } elements: [ { name: 'headline', x: 960, y: 400, type_data: { text: 'Hello', fontSize: 120 } }, ... ] Use after calling get_element_schema to confirm the type_data shape per element_type. Items within one call are applied in order; returns one result entry per input item so partial success is fine. Native is the default; compute boxes and eased keyframes in run_script (layout.row/grid/split, anim.stagger, native.box/text/tween — worked example: get_design_guide({topic: "stdlib", query: "native-elements"})). An `animation` item with `code` lands as a draft you refine in place with edit_animation(element_id, project_id). Across a cut: an item `{continue_from: <element_id or group id>, clip_index?, start_time?, end_time?, type_data?: {animation_setting: {exit}}}` carries that element, group or animation into the next clip (or clip_index) as it was at its end, so consecutive scenes in one world don't reset; end_time and an exit let it leave on time. It returns the new element_ids and end_state: the transform the copy starts with, as applied (positionX, positionY, width, height, rotation and held values such as opacity or scale; for a group {group, elements: {<id>: state}}), so a keyframe that starts from it continues without a jump. Reuse instead of rebuilding: an item may pass `component_id` INSTEAD of element_type/type_data to insert a saved component from this workspace exactly as stored — no generation, instant — returning every new element_id plus its parameter_schema; set its content afterwards with update_elements(type_data.parameter_values). Find them with find(type='element_components'). Use `base_component_id` (with element_type='animation' and a prompt) only when you want a NEW variant rather than that component. Z-order: list position IS z-index — later renders on top — and a new element goes on top by default. Pass `insert_at: 'back'` to put it behind what's already there, or `insert_at: {before: id}` / `{after: id}` to land next to a specific element — that also puts the new element in THAT node's group, which is the only way to place inside one. `reorder_elements` rewrites the whole order in one call, grouped clips included. `group` + `insert_at: {before|after}` together: what the reference is relative to decides what gets positioned. Point at a node INSIDE the group and the ELEMENT takes that slot among its new siblings. Point at one OUTSIDE it and the GROUP takes that slot, with the element inside — which is how you put a backdrop pattern of N elements at a chosen depth as one hideable unit: hoist both into `defaults` and the first item seats the group, the rest just join it. The one refusal left is naming a reference outside a group that already exists somewhere else, since moving an established group is not what adding one element to it should do; seat the group where you want it in the call that CREATES it, because there is no reposition afterwards. `front`/`back` with a `group` follow the same principle: they address the GROUP only while the element is alone in it — the call that creates it — and once the group has other members they address the ELEMENT within the group's interior, so they will not move an established group either. Grouping (`group: "<name>"`) never changes coordinates but does affect z-order: a group's members render contiguously at the group's slot, and a NEW group takes the slot of its first member, so grouping scattered elements pulls them together at the lowest member's slot. Concurrency: within ONE call every element lands in a single save. Across calls the conflict domain is the CLIP's element list, not the individual element, so you can fan this tool out across parallel subagents targeting DIFFERENT clips. Two concurrent add_elements calls on the SAME clip are NOT safe: every add claims that clip's element list, so the later call is REJECTED ('changed since this edit was based on') and nothing it sent is written — batch all of a clip's elements into ONE call instead. A rejection is not last-write-wins: re-read and re-apply. Do NOT run it concurrently with a whole-clip or whole-project mutation on the same guide (update_clips on that clip, add_clips/remove_clip/split_clip/duplicate_clip, add_audio, update_project) — those rewrite a larger scope and would clobber the element. Element-type quirks (handled per-item): • zoom → x/y/width/height are ignored; use centerX/centerY in type_data • image → provide x/y/width/height (the clip is located by clip_index; the clip_id input is accepted but unused) • animation → x/y/width/height default to the full canvas if omitted (the clip is located by clip_index) • avatar → an AI presenter; type_data.avatarId from find(type='avatars'). Omit x/y for the default bottom-right position (both 0 also means default) and width/height for the default size; width sets the size and height follows the look. The result's `avatar` says whether export will render it and what it costs — read get_element_schema('avatar') before the first one. For everything else, x/y/width/height are required. Animation: pass a top-level `keyframes` array (sibling of x/y/type_data, NOT inside type_data) — entries are { timestamp, positionX?, positionY?, width?, height?, interpolation? } in canvas pixels. positionX/Y use the SAME origin as the element's x/y — for text sent with y and y_anchor, positionY follows the anchor too, so `native.text(box, …)` with `native.tween(t, d, {positionY: y + 40}, {positionY: y})` slides onto the anchored line. Keyframe timestamps are clip seconds, never negative: an anticipation wind-up goes inside the clip. Text caveat: width/height are not keyframable on text — animate its size with fontSize (letterSpacing/lineHeight/padding* are also keyframable). Position origin: for TEXT `y` is the vertical CENTRE when centre-aligned and the TOP otherwise; every other type uses the top; `x` is the left edge, except TEXT where alignment picks it: left→left, center→centre, right→right. To centre a label in a row, pill, chip, card or beside an icon: pass the container's centre line as y with y_anchor:'center'. The server centres the measured text in it, so it is one number and it holds for wrapped text. Add type_data.fit{max_height} whenever the text could wrap, so the box stays inside the space you gave it. y_anchor is a directive for computing the stored y, not a property that sticks — repeat it on any later call that moves the same label.
Add sync point
Insert one sync marker on a clip's transcript. Use this when: - The user is explicit about WHERE the camera should pause / cut (e.g. "sync the word 'submit' to 4.2s of the demo"). - `auto_sync` ran but missed a step you care about. How matching works: - `word`: case-insensitive, punctuation-stripped. The first match in the transcript is used unless `occurrence > 1`. - `occurrence`: 1-indexed — pass 2 to target the SECOND time that word appears, 3 for the third, etc. Required when the word repeats. - `timestamp_seconds`: clip-relative seconds. When the clip has run TTS already (`generated_timestamps` present), the server inverse-maps this to original-recording seconds automatically. Constraints: the clip MUST be a video clip with a source recording (otherwise the frame thumbnail can't be extracted). The transcript must already contain the word — if not, you'll get `word_not_found` with a 200-char excerpt of the transcript to help you retry.
Analyze audio
Analyze an audio file. Modes: - transcript: Speech-to-text with word-level timestamps — returns `{language, full_text, words}` where each word is `{word, start_ms, end_ms, punctuated_word}`. ⚠ MILLISECONDS here; get_clip's `voiceover_words` gives the same words in SECONDS as `{word, start, end}`. Use for caption timing, script editing, or word-level visual sync. Works on narration and on sung lyrics: the provider is picked from the content, and if it returns nothing the other one is tried automatically. So an empty `words` means the audio genuinely has no intelligible speech, not that the wrong engine ran. - silences: returns `{silences, total_silence_ms}`, each span `{start_ms, end_ms, peak_db}`. Use for auto-trim, smart-split, or pause-aware editing. - beats: returns `{tempo_bpm, beats_ms}` — beats_ms is an array of MILLISECOND positions. Empty for non-music. Use to align animations/zooms to a beat. - features: returns `{duration_ms, peak_db, rms_db, lufs, has_music, has_speech, speech_share}` — loudness plus two INDEPENDENT hints — `has_music` (beats hold a steady period) and `has_speech` (at least 40% of the audible seconds sound like talking; `speech_share` is that share, 0-1). Instrumentals read false; so do sung vocals and narration under a loud bed, so when the words matter, use transcript. Cheap dispatcher — call once to pick a mode, or for duration_ms to pass as add_audio's source_duration. - energy: loudness over time — `{samples_per_second, start_ms, db}`, db one RMS dBFS value per 1/samples_per_second s from start_ms (default 4 a second; energy_options.samples_per_second 1-20). Read builds, dips and hits from it. - sections: how a track is built — `{loud_db, sections: [{label, start_ms, end_ms, db, onsets_per_s}], drops: [{t_ms, rise_db, quiet_start_ms?, quiet_end_ms?}]}`, label intro | build | drop | main | breakdown | outro; a drop's t_ms is the hit (within ~10 ms), quiet_* the dip just before it. Set animation cues on beats (beats mode) or drops. - describe: what the audio IS — `{kind: speech|music|mixed, classification_confidence, duration_seconds, music?: {tempo_bpm, key, mood, genre, energy, instruments, description, suggested_search_query}, speech?: {...}}`. Pass suggested_search_query to find(type='music') for a similar track. Speech is not transcribed here; use transcript for the words. Source: provide exactly one of mcp_upload_id (from upload tool) or file_url (already-public URL, e.g. a find(type='music') result or Clueso CDN file). Optional time range: range_start_ms / range_end_ms crops the analysis window.
Auto sync
Run the agentic auto-sync pipeline on a clip with a source recording: detects natural sync points (UI changes, narrated steps) and inserts sync-marker nodes into its transcript. Required before voiceover TTS on video clips (clueso://docs/sync-points). Skips (no run): "audio_extracted" (read-only transcript); "clip_busy" + held_by (retry later); "clip_too_long" + {clip_id, duration_label} (trimmed window over 5 min; never quote the limit): split_clip it into shorter clips and auto_sync each. Returns once started; markers land a few seconds later, so poll get_clip before TTS.
Captions
Read and edit a clip's CAPTIONS (subtitles) — what they say, where one caption ends and the next begins, when each shows, captions not tied to the voiceover, and translation. Captions are built from the clip's voiceover words: each caption is a run of words, addressed by its `start_word_index`. Start with action="list" on the clip — it returns `blocks` (voiceover captions: start_word_index, end_word_index, start/end in clip seconds, text, transcript_text, words, edited, retimed, mergeable), `manual_captions` ({caption_id, start, end, text}), `active_language` and `translated_languages`. Then: - edit (start_word_index, text) — change what ONE caption says on screen. The voiceover audio, its words and timing are untouched; to change what is SPOKEN use voiceover_batch. reset (start_word_index) restores the transcript text. - split (start_word_index, split_word_index) — cut a caption in two; split_word_index is the word that STARTS the second caption (block word i = start_word_index + i; not the first word). Edited text, per-caption style and custom timing are divided between the halves — re-check both and edit them if the cut landed badly. merge (start_word_index of the SECOND caption) only undoes a split (`mergeable: true`); other boundaries come from the transcript's sentences and pauses. - timing (start_word_index, start_time, end_time) — when one caption shows, in seconds from the START OF THE CLIP. timing_reset returns it to its words' own timing. - manual_add (start_time, end_time, text) → caption_id; manual_edit (caption_id, and text and/or start_time/end_time); manual_remove (caption_id). Manual captions have their own text and window — use them on clips with NO voiceover (list returns no blocks there) or to fill a gap. Adding/editing one turns captions on for the clip. They show without word highlighting. - translate (language: id like "fr" or name like "French") — translate caption TEXT (edited and manual captions included) using the workspace's translation rules and glossary. Omit clip_index for every clip. The new language becomes the one shown; earlier languages are kept. The voiceover stays in its language (use set_voice for that). One translation call per clip, so a long project takes a while — do one clip first if only one was asked about. - language (language: an already-translated id, or "original") — switch which translation is shown, instantly, without re-translating. Omit clip_index for every clip. Rules: a caption lasts at least 0.1s, stays inside the clip, and never overlaps another caption; anything else is REFUSED with the allowed range — read it and retry. While a translation is shown, edit/manual_edit change the translated text and split is refused (switch to "original" first). Custom timing is tied to a caption's exact words and stops applying if the voiceover is regenerated. To burn captions into an exported video use export_project(captions=true). Concurrency: clip-scoped mutation (conflict domain: the clip's caption settings) — serialize calls on the SAME clip; different clips run in parallel. translate/language without clip_index touch every clip: run them alone.
Create clueprint
Create a new clueprint (reusable video template). A clueprint is a structured file directory with design notes, composition rules, and screenshots that can be used to generate videos. Use human-readable folder categories: design/ (colors, typography, backgrounds, animation), rules/ (composition, voiceover, editing), screenshots/ (rendered clip previews). See the "Creating Clueprints" section in the system instructions for the full structure. If source_guide_ids are provided, guide data is extracted clip-by-clip into the clueprint (animations and images described, auto-element rules learned; can take minutes). Each non-empty decision list in the reply (animations_pending_mode, logo_animations, images_pending_mode, clips_pending_voiceover_policy, multi_split_summary, slide_count_strategy, the *_by_role groups, discovered_element_types_by_clip_type) is a choice to ask the user, then record with update_clueprint(decisions). A clueprint is THE FORMAT (layouts, pacing, motion, transitions, voiceover style, music, captions, effects); a project built from it takes its colors, fonts and logos from that project's brand kit. brand_locked: true keeps the clueprint's own colors, fonts and logos for projects in this workspace (for a template made for one brand, e.g. a co-marketing piece).
Create folder
Create a folder in the workspace, optionally inside another folder, to organize projects. Returns { folder_id, name, parent_folder_id, already_existed }. If a folder with the same name (case-insensitive) already exists in that parent, it is returned with already_existed=true instead of creating a duplicate — so it is safe to call to "ensure" a folder exists. Put projects in it with create_project(folder_id=...) or update_project(project_id, folder_id=...). List existing folders with find(type='folders').
Create project
Create a new blank Clueso project. Returns the projectId and initialClipId — the project starts with one blank clip already at index 0 (default short duration). Use update_clips to resize/retitle clip 0, add_clips(kind='blank') to append more clips, add_elements to place content, and add_audio to attach a project-level music track. Optionally place the project inside a folder (use find(type='folders') to find folder IDs, or create_folder to make one) and set a description at creation time. From a clueprint: it sets the format (layouts, pacing, motion, voiceover, music, captions) and this project's brand kit the identity (colors, fonts, logos, icons); see get_clueprint's `brand`. Brand kit: a project follows the workspace's default brand kit unless given one. Pass brand_kit_id (from find(type='brand_kits')) to build this project with that kit, e.g. one project per brand; the reply's brandKit says which kit it uses. Then get_design_guide({project_id, select: [...]}) returns that kit's colors, fonts, logos and guidelines. Start it voiced (one or the other): • script — one blank clip per paragraph (blank-line separated), each with AI voiceover generated from it; clip lengths follow the speech (generation runs in the background, ~seconds per clip). Returns clip_ids. • audio — an audio upload (an mcp_upload_id or a Clueso upload_id): it becomes clip 0's voiceover as the original narration, transcribed (script + captions), and the clip takes its length. Returns duration and word_count.
and 26 more.
How to connect Clueso MCP
Sign in to Zeplik
Create a free Zeplik account or sign in. New accounts start with free credits, so you can try Clueso MCP immediately.
Connect Clueso MCP
Open Settings and go to Connectors, then press Connect on Clueso MCP. You can also connect from the Clueso MCP page in the app.
Approve access to Clueso MCP
Approve access on Clueso MCP's secure consent screen. You are returned to Zeplik and can start giving instructions that use Clueso MCP.
Frequently asked questions
- Can I use Clueso MCP with Zeplik?
- Yes. Clueso MCP is available as an integration on Zeplik. Connect it once and the AI assistant can work with your Clueso MCP account inside any conversation.
- What can Zeplik do with Clueso MCP?
- Once connected, Zeplik has 15 read and 38 write actions for Clueso MCP. Create and edit Clueso product videos, documentation articles, clips, voiceovers, captions, animations, and exports through Clueso's hosted MCP.
- How do I connect Clueso MCP to Zeplik?
- You connect Clueso MCP with a secure one-click sign-in (OAuth): press Connect in Settings under Connectors and approve access on Clueso MCP's consent screen.
- Does Zeplik change things in Clueso MCP without asking?
- No. Zeplik reads from Clueso MCP by default. Any action that changes data in Clueso MCP requires write access, which stays off until you enable it in Settings under Connectors.
- How much does connecting Clueso MCP cost?
- Connecting Clueso MCP is free. You only spend Zeplik credits when the assistant runs, and new accounts start with free credits.
Related design integrations
- CreatomateCreatomate is an API for generating and managing automated videos, images, GIFs, and reusable media templates.
- Dynamic MockupsDynamic Mockups provides APIs for generating product mockups, rendering templates, managing catalogs and collections, and creating AI-powered image.
- DynapicturesGenerate Hundreds of Personalized Images in Minutes. DynaPictures is a cloud-based solution for dynamic image generation. Connect your preferred data.
- EranolEranol provides API-driven video, audio, and media conversion workflows powered by FFmpeg.
- FramerFramer is a website builder and design platform whose Server API supports project publishing, CMS, localization, canvas, asset, code, and agent.
- GetTranscribeGetTranscribe converts supported video and media URLs into searchable transcriptions and provides tools for managing transcription jobs, results, and.
More on Zeplik
Connect Clueso MCP to your AI assistant
Every model, one chat. Bring Clueso MCP into Zeplik and let the assistant do the work.