# ViralSpin MCP — the video editor your AI agent operates

[![MCP Registry](https://img.shields.io/badge/MCP-registry-blue)](https://registry.modelcontextprotocol.io/v0/servers?search=viralspin)
[![npm](https://img.shields.io/badge/npm-%40viralspin%2Fmcp-red)](https://www.npmjs.com/package/@viralspin/mcp)
[![license](https://img.shields.io/badge/license-MIT-green)](./LICENSE)

Turn a talking-head clip + a folder of B-roll into a polished vertical short — and **let Claude do the edit**. Point it at your footage in plain English; it transcribes, picks B-roll cutaways matched to what's said, adds captions + a hook, and renders a 9:16 short. Then publishes to TikTok, Instagram, or YouTube. No timeline-wrangling required.

> **The agent operates a real timeline.** Swap a clip, trim it, reorder scenes, cut a span — all by asking. Edits are instant; you render once when the cut is right.

![demo](docs/demo.gif) <!-- TODO: the split-screen "Claude edits, clips stream onto the timeline" clip -->

## Quick start

```bash
# Claude Code
claude mcp add viralspin -- npx -y @viralspin/mcp

# or Claude Desktop — add to claude_desktop_config.json:
{
  "mcpServers": {
    "viralspin": { "command": "npx", "args": ["-y", "@viralspin/mcp"] }
  }
}
```

Then just ask:

```
Turn my A-roll at C:/clips/talk.mp4 into a 9:16 short, using B-roll
from C:/my-broll and my Google Photos.

Publish that to TikTok and Instagram with the caption: posting through the chaos.
```

## What the agent can do

| Tool | What it does |
|---|---|
| `create_video_assembly` | A-roll + B-roll (local files, a folder, URLs, or Google Photos) → a rendered vertical short. Local or hosted. |
| `suggest_clips` / `swap_clip` | See the cutaways; swap one for better-fitting B-roll (with a `reason`). |
| `trim_clip` / `remove_span` / `reorder_scenes` | Granular timeline edits — instant, no re-render. |
| `render_project` | Bake captions/overlays into the final MP4 (the one render). |
| `publish_now` / `schedule_post` / `send_to_drafts` | Post to TikTok / Instagram / YouTube. |
| `generate_caption`, `create_kinetic_text`, carousels, image ads | The rest of the content pipeline. |

Edits are **instant and free** (they patch the timeline); `render_project` is the single cloud render. Iterate the cut as much as you like, then finalize once.

## Open source

The MCP server, the editor, and the agent verbs are **MIT** — use them free. Cloud generation (AI B-roll, rendering, publishing) runs on ViralSpin's infrastructure and is metered as credits; sign in at [viralspin.ai](https://www.viralspin.ai). You never paste an API key for the AI — the heavy lifting is server-side.

- Listed in the official **MCP registry**: `ai.viralspin/viralspin`
- Hosted connector (no install, for URL / Google Photos workflows): `https://mcp.viralspin.ai/mcp`

## Local vs hosted

- **Hosted (the default):** the cloud pipeline does the heavy lifting — assembly, AI B-roll, rendering — and every edit opens in the web Swap & Refine editor. B-roll from Google Photos / URLs / your synced library. Needs a [viralspin.ai](https://www.viralspin.ai) account (generation is metered as credits); no API keys to paste. The `mcp.viralspin.ai/mcp` hosted connector is the same, zero-install.
- **Local (advanced):** point `VIRALSPIN_ASSEMBLY_DIR` at a local engine checkout to read your disk — index a folder of clips, select B-roll contextually, and render locally. The npm package ships without the engine, so the local-render tools route you to the hosted path until that env var is set.

Either way, the agent reads local files *to upload them* (A-roll, a B-roll folder); only on-disk rendering needs the local engine.

## License

MIT — see [LICENSE](./LICENSE).