---
name: clipspeed-mcp
description: Use when the user wants to turn a video or niche into ready-to-post short-form clips via ClipSpeed — e.g. "find and clip the hottest video this week", "grow my AI page", "clip this YouTube video and give me the top 3", "save those clips to my computer", "restyle the captions", or "schedule the winner to TikTok". Requires the clipspeed-mcp server to be connected (a csai_live_ API key from a paid ClipSpeed plan or the $1 trial).
---

# ClipSpeed MCP

Drive ClipSpeed end-to-end from one prompt: discover the fastest-growing video in a niche, turn any video into scored vertical clips with animated captions, save them to disk, restyle the look, and schedule the winners across five platforms. Assumes the `clipspeed-mcp` server is connected.

> Install: copy this file to `.claude/skills/clipspeed-mcp/SKILL.md` (Claude Code) or your client's skills dir. It ships with the MCP so the agent uses the tools well.

## Core principle

The user speaks in **outcomes** ("give me today's clips", "grow my page", "schedule the best one"), not mechanics. Do the plumbing silently and narrate only the interesting parts: *why* you picked a video, and what came out. Lead with the clips, not the process.

## The tools

| Tool | When to use | Key args |
|---|---|---|
| `discover_trending` | "find the hottest / grow my page" | `niche`, `days` |
| `clip_video` | after a pick, or a URL the user gives | `video_url`, `caption_style`, `aspect_ratio`, `clip_count`, `platform` |
| `get_clip_status` | poll until `status: complete` | `job_id` |
| `download_clip` | "save them", "download to my computer" | `job_id`, `clip_index?` |
| `get_usage` | "how many credits do I have left?" | — |
| `restyle_captions` | "make the captions bolder / hormozi" | `project_id`, `style` |
| `schedule_post` | "post it", "schedule to TikTok" | `clip_id`, `platforms[]`, `caption?`, `title?`, `scheduled_at?` |
| `list_scheduled_posts` | "what's queued?" | `status?`, `platform?`, `limit?` |
| `cancel_scheduled_post` | "cancel that post" | `post_id` |
| `list_clips` | "show my past jobs" | `limit?`, `status?` |

## The standard flow

1. **Check access (once).** On the first real action, call `get_usage`. Confirm there are credits (1 credit = 1 minute of source video) and note the plan. If access is missing you'll get a `subscription_required` error with an `upgrade_url` — tell the user plainly and stop.
2. **Discover** — call `discover_trending` with the user's niche (omit `niche` to reuse the remembered one). Returns a ranked `pick` plus `candidates` with `viewCount`, `velocity` (views/hour), `channelLift` (× the channel's own norm), and a one-line `why`. **Tell the user which video you picked and the reason** ("1.8M views in 36h, 3.2× this channel's norm"). Skip this step if the user handed you a specific URL.
3. **Clip** — call `clip_video` with the pick's `video_url` (or the user's URL). Pass a `caption_style` if they asked for a look (see Styles). Returns a `job_id`.
4. **Check** — poll `get_clip_status` with the `job_id` every ~30–60s. Report progress conversationally. When `status` is `complete`, you have clips with `viral_score`, `title`, `duration`, and a `video_url`.
5. **Present the top clips.** Show the **highest `viral_score` first** — the top 3–5, not all of them.
6. **Download (optional)** — if the user says "save them" / "download", call `download_clip` with the `job_id` (and `clip_index` for just one). Files land in `~/Downloads`. This is the local-disk win a hosted tool can't do.
7. **Schedule (optional)** — if the user says "post it", call `schedule_post` with the clip's id and the `platforms` array. Default to `scheduled_at` omitted (ASAP) unless they gave a time.

## Caption styles

The look is chosen at `clip_video` time via `caption_style` (or changed later with `restyle_captions`):

- **karaoke** — green highlight, bold (default, highest-converting)
- **hormozi** — yellow pill, black text (bold branded)
- **beasty** — pink, largest font (MrBeast energy)
- **fire** — orange highlight
- **youshaei** — clean blue highlight
- **cinematic** — gold italic, refined

Aspect ratio defaults to `9:16`; use `1:1` or `16:9` only if asked.

## Publishing: connect platforms first

`schedule_post` targets **tiktok, youtube, instagram, x, linkedin**. The account must be connected in the ClipSpeed app first. If a post fails to schedule because a platform isn't connected, tell the user to connect it in the app's Scheduler, then retry. Default to the user's stated platform(s); don't fan out to all five unless asked.

## Common mistakes

- **Don't make discovery the hero.** The user cares about clips, not that you searched YouTube. Lead with the pick + why, not "I ran 5 searches."
- **Don't dump every clip.** Show the top 3–5 by `viral_score`.
- **Don't schedule public/everywhere by default.** Post to what the user asked for, when they asked.
- **If `discover_trending` returns `ok:false` / `no_fresh_candidates`**, the shared YouTube search quota is momentarily exhausted — say so plainly and offer to retry, or ask for a specific video URL to clip directly.
- **Out of credits?** A `clip_video` or `discover` call returns `insufficient_credits` with `credits_remaining`, `credits_needed`, and an `upgrade_url`. Relay it plainly and point to the upgrade link — don't retry in a loop.
- **One niche is remembered.** On a bare "give me today's clips", call `discover_trending` with no `niche` to reuse it; it also auto-skips videos already clipped.
- **Jobs take ~10–30 minutes.** Set expectations, poll patiently, and don't declare failure early.