clipflow-mcp

Model Context Protocol (MCP) server for Clipflow — repurpose YouTube videos and podcasts into platform-native short-form clips, directly from Claude Desktop, Claude Code, or any MCP-compatible AI client.

What this does

Lets you say things like:

"Take this YouTube link, repurpose it into 5 TikTok clips and 3 Instagram Reels in my Clipflow workspace."

And Claude calls Clipflow under the hood — imports, finds the best hooks, generates clips for each platform — all without leaving your AI client. Drafts land in your Clipflow workspace ready for human approval before publishing.

9 tools exposed

Write tools — mutate state, drafts always require human approval before publishing:

| Tool | What it does | |---|---| | clipflow_repurpose | The main one. Full pipeline (import → hooks → clips) in one call | | clipflow_import_youtube | Import a single YouTube video, get a content_id | | clipflow_find_best_hooks | Get ranked viral-hook moments for a content item | | clipflow_generate_clips | Generate draft clips for chosen platforms | | clipflow_schedule_post | Schedule an APPROVED output (after human reviews in Clipflow UI) |

Read tools (added in 0.2.0) — inert by design, surface context so the agent can answer questions without forking you to the Clipflow UI:

| Tool | What it does | |---|---| | clipflow_list_workspaces | Returns workspace name, slug, type, timezone, and current Auto-Pilot mode + threshold | | clipflow_read_brand_voice | Returns your active brand voice (tone, avoid, example hook) + a ready-to-inject prompt instruction | | clipflow_list_scheduled_posts | Lists upcoming/recent scheduled posts with platform, status, retry count, error messages | | clipflow_get_workspace_stats | Snapshot: content totals, drafts last 7d, scheduled this week/month, autopilot productivity |

Install

1. Get your Clipflow API token

1. Go to clipflow.to/settings/api
2. Click "New token"
3. Name it (e.g. Claude Desktop), pick scopes you want (or leave blank for full workspace access)
4. Copy the cfk_... token — it's only shown once

2. Configure your MCP client

Claude Desktop

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

{
  "mcpServers": {
    "clipflow": {
      "command": "npx",
      "args": ["-y", "clipflow-mcp"],
      "env": {
        "CLIPFLOW_API_TOKEN": "cfk_your_token_here"
      }
    }
  }
}

Restart Claude Desktop. You should see a 🛠️ icon at the bottom showing 9 Clipflow tools available.

Claude Code (CLI)

Easiest path — use the built-in command (writes to the right config file for you):

claude mcp add clipflow \
  -e CLIPFLOW_API_TOKEN=cfk_your_token_here \
  -- npx -y clipflow-mcp

Or edit ~/.claude.json (note: .claude.json, not .claude/mcp.json) directly:

{
  "mcpServers": {
    "clipflow": {
      "command": "npx",
      "args": ["-y", "clipflow-mcp"],
      "env": { "CLIPFLOW_API_TOKEN": "cfk_..." }
    }
  }
}

Then run claude mcp list to confirm Clipflow is registered.

Other clients (Cline, Continue, custom)

Any MCP-compatible client with stdio transport. The command is:

CLIPFLOW_API_TOKEN=cfk_... npx -y clipflow-mcp

Usage examples

Example 1: One-shot repurpose

You: Repurpose https://youtube.com/watch?v=abc into 3 TikTok and 2 Reels using my Clipflow.

Claude: (calls clipflow_repurpose)

✅ Repurposed "Joe Rogan #2200 — Bryan Cranston" into 2 of 2 platforms. Found 8 hooks; selected the top ones for clips. Output IDs: op_xxxx, op_yyyy. Next step: Approve in the Clipflow Review UI, then I can schedule them.

Example 2: Multi-step workflow

You: Import this YouTube link first, then show me what hooks it found.

Claude: (calls clipflow_import_youtube, then clipflow_find_best_hooks)

Imported "Lex Fridman #459". Top 5 hooks:

1. [0.85] "The first time I cried in my office was about money…"
2. [0.79] "Most founders never tell you what year 2 actually looks like"
3. [0.72] "I almost quit at 11pm on a Tuesday in March" …

Example 3: Schedule (after approval)

You: I just approved the LinkedIn version in the Clipflow review tab. Schedule it for Monday 9am UTC.

Claude: (calls clipflow_schedule_post)

📅 Scheduled output op_xxxx for 2026-05-26T09:00:00Z.

Example 4: Status check (0.2.0+)

You: How's my Clipflow this week? Anything failing?

Claude: (calls clipflow_get_workspace_stats + clipflow_list_scheduled_posts)

📊 Workspace snapshot:

• 12 content items (3 ready, 0 processing, 1 failed)
• +5 drafts in the last 7 days
• 8 scheduled this week · 23 this month
• ⚠️ 2 scheduled posts currently failing — auth issues on Instagram

📅 Upcoming this week: 🕒 [linkedin] 2026-05-27 09:00 — scheduled ⚠️ [instagram_reels] 2026-05-27 14:00 — failed (3 retries) 🕒 [tiktok] 2026-05-28 10:00 — scheduled …

Example 5: Brand-aware drafting (0.2.0+)

You: Draft me a LinkedIn post about our new feature, in our brand voice.

Claude: (calls clipflow_read_brand_voice first to align tone)

Brand voice: "Punchy Founder" Tone: Direct, founder-led, no hedging · Avoid: corporate fluff, "we believe…" · Match this hook energy: "Just shipped X. Here's what broke."

(then drafts the post in that voice)

Authentication & security

• Tokens are hashed at rest (SHA-256) on Clipflow's side. Plaintext is only shown once at mint time.
• Per-workspace: each token is bound to one workspace; multi-workspace agents create multiple tokens.
• Scoped (optional): tokens can be restricted to specific actions (actions:read, actions:write, content:read, content:write). Default = full workspace access.
• Revocable anytime at /settings/api — takes effect immediately.

Never put the token in code, never paste it in shared chats, never commit it to git. Treat it like a password. If you suspect it leaked, revoke + mint a new one.

Environment variables

| Var | Required | Default | Purpose | |---|---|---|---| | CLIPFLOW_API_TOKEN | ✅ Yes | — | Bearer token from /settings/api | | CLIPFLOW_API_URL | No | https://clipflow.to/api/v1 | Override for self-hosted or preview deployments |

The AI co-pilot — three modes you control

External agents (Claude, etc.) cannot promote a draft past review on their own. The decision to skip human-review lives with YOU, set per-workspace in Clipflow:

| Mode | What happens to drafts | |---|---| | Co-Pilot (default) | Every draft hits your review queue. Nothing publishes without your approval. | | Auto-Pilot | High-confidence drafts (≥ your threshold) publish automatically. Lower-scored ones wait for review. | | Full Auto | Every draft publishes automatically. Power-user only — turn on once your brand voice is stable. |

                    ┌─ Co-Pilot:   manual review queue
Agent: clipflow_*  ─┼─ Auto-Pilot:  confidence ≥ threshold? → publish, else review
                    └─ Full Auto:   publish all

Set the mode at /settings/workspace. Per-channel overrides ("LinkedIn = Co-Pilot, TikTok = Auto-Pilot") live in /settings/channels, per-content overrides on each video's detail page.

Every auto-decision is logged with a reason you can inspect — what confidence the AI assigned, which hook pattern, what threshold was active. No black box.

If you try to schedule a non-approved output via clipflow_schedule_post, you'll get a clear error — the schedule call respects the same state machine the UI enforces. This is by design.

Development

# Clone the repo (mcp-server lives under packages/)
git clone https://github.com/adrianoncode/Clipflow.git
cd Clipflow/mcp-server

# Install + run in dev mode
pnpm install
CLIPFLOW_API_TOKEN=cfk_... pnpm dev

# Build for publish
pnpm build

# Typecheck only
pnpm typecheck

Troubleshooting

CLIPFLOW_API_TOKEN env var is not set

Add the env section in your MCP client config (see Install section above). Restart the client.

Clipflow API 401 unauthorized

Your token was revoked, expired, or you copied it wrong. Mint a fresh one at /settings/api.

Clipflow API 403 insufficient_scope

Your token doesn't have the scope required by the action you're trying to call. Mint a new token with the required scope (or with no scopes selected = full access).

network_error

The MCP server can't reach clipflow.to. Check your internet, or override CLIPFLOW_API_URL if you're on a self-hosted instance.

timeout — "Clipflow API did not respond within 310s"

The longest legitimate call (clipflow_repurpose running all 4 platforms end-to-end) caps just over Vercel's 300s function limit. A genuine timeout usually means a YouTube fetch or LLM call stalled mid-pipeline. The work may have completed server-side — check your Clipflow workspace's Review tab before retrying so you don't double-import the same video.

Output says "must be human-approved"

That's the gate — go to the Clipflow Review UI and approve the output. Then tell Claude to schedule it.

License

MIT — see LICENSE file.