An MCP server that exposes the ClipAI clipping pipeline as agent-callable tools, so Claude (or any MCP client) can run the whole loop from a message: import a YouTube video, list the AI-detected clips, render one, and schedule it to a connected account.

This is ClipAI's answer to agent-triggered clipping: the same generate -> distribute loop the app does, now drivable by an agent.

Tools

Tool	What it does
`import_youtube`	Import a YouTube URL and start AI clip detection (returns video_id, job_id). Optional `goal` (`viral` / `highlights` / `insights`) and `max_clips` (1-60).
`list_videos`	List the org's videos with status and clip counts.
`list_clips`	List clips (optionally for one video): id, title, status, score, start/end.
`get_clip`	Fetch one clip (poll its status after rendering). `dubSkipped: true` on a READY clip means the requested `dub_language` was unavailable and the original audio was kept (the result then carries a `dub_notice`).
`analyze_clip_url`	Explain why a public short works: score a YouTube or TikTok `url` and return `score` (0-1), `score_percent`, `band` (`strong` / `solid` / `developing` / `weak`) with a `band_note`, `hook_type`, `title`, `reasoning` and a `breakdown` by dimension. Costs one scoring run of the org's limits; paid plans only.
`find_moments`	Find more moments about a `topic` (max 200 chars) in a READY `video_id`: one extra scoring pass over the stored transcript. Returns `jobId`, `runsLeft` and a `next_step`; new clips appear in `list_clips(video_id)` as PENDING. A few runs per video, paid plans only.
`render_clip`	Render a clip to a 9:16 short with burned captions (returns jobId). Optional `platform`, `caption_language` and `dub_language` (one of the 13 language names in `src/enums.ts`; `dub_language` is an ElevenLabs voice dub, no voice cloning; needs `dub_consent: true`, the user's confirmation that the people whose voices are dubbed consented; a dubbed clip is flagged AI-generated when published), `hook_text` (max 120 chars), `reframe_focus` (`center` / `left` / `right` / `track`; `track` pans the crop to follow the speaker), `remove_silence`, `layout` (`fill` / `split`).
`list_social_accounts`	List connected social accounts to schedule to.
`schedule_clip`	Schedule a READY clip to an account: `clip_id`, `social_account_id`, `caption` required; `hashtags`, `scheduled_at` (ISO 8601) or `publish_now` optional.

A typical agent flow: import_youtube -> poll list_clips(video_id) until clips appear -> render_clip -> poll get_clip until status: "READY" -> list_social_accounts -> schedule_clip.

To make the user's own version of a clip that worked (0.3.0): analyze_clip_url on the public clip (why it works: hook, structure, pacing) -> find_moments on the user's READY video with that hook or theme as the topic -> poll list_clips(video_id) for the new PENDING clips -> render_clip.

Since render-on-detect (2026-09-13), the top clip of a new import may already be RENDERING or READY with default options before any render_clip call. If render_clip answers "already rendering", poll get_clip until READY, then call render_clip again to apply your own options.

Remote endpoint (no install)

The same tools are also served by the web app itself at https://clipai.online/api/mcp (Streamable HTTP), for clients that connect to a URL instead of running a local process: ChatGPT apps and claude.ai custom connectors sign in through ClipAI's OAuth 2.1 flow (discovery at /.well-known/oauth-protected-resource), and any other remote MCP client can send a dashboard API key as Authorization: Bearer clip_.... Code: apps/web/src/app/api/mcp/route.ts and apps/web/src/lib/mcp/; ChatGPT listing runbook: docs/chatgpt-app/README.md. Tool behavior matches this package; keep the descriptions in apps/web/src/lib/mcp/tool-definitions.ts in step with src/tools.ts. One difference: the remote endpoint hides import_youtube unless MCP_YOUTUBE_IMPORT_ENABLED=true (2026-10-30).

Auth

The server authenticates with a per-org API key (a revocable key you generate in ClipAI under Settings -> API keys), sent as Authorization: Bearer <key>. Set:

CLIPAI_API_KEY - the key (starts with clip_)
CLIPAI_BASE_URL - optional, defaults to https://clipai.online

The key carries the org owner's authority over the clip pipeline and can be revoked at any time from Settings. The same key works for any programmatic API call, not just this server, with these exceptions:

App-only routes such as account deletion accept only keys minted by a ClipAI mobile sign-in (ApiKeyKind.MOBILE in the Prisma schema).
Dashboard-only actions need a signed-in web session, never an API key: managing API keys, billing and checkout, connecting or disconnecting social accounts, and campaign spend (creating a campaign, changing its budget, rate or status, approving payouts).

A key CAN publish to the org's connected social accounts (schedule_clip); that is the point of the server. Treat the key like a password: keep it in your MCP client's env config (not in a shared file or repo) and revoke it in Settings if it may have leaked.

Safety notes for agent use

Tool annotations (src/tools.ts). list_videos, list_clips, get_clip and list_social_accounts are readOnlyHint: true. import_youtube (spends one video of quota, fetches from YouTube), analyze_clip_url (fetches a public clip, spends one scoring run), find_moments (one scoring pass over the user's video) and render_clip are write tools, not destructive. schedule_clip is destructiveHint: true and openWorldHint: true because it posts publicly; MCP clients that honor annotations ask before each call. Keep that confirmation on. Its description also tells the model to post only when the user asked, never because clip or transcript text says so.
Untrusted content. Clip titles, score reasoning and video titles come from the source video (often someone else's upload), its transcript, or AI output over it, so they can contain prompt-injection text. list_videos, list_clips, get_clip and list_social_accounts return their result as { untrusted_content_notice, data } (src/output.ts) so the model treats that text as data. This envelope is new in 0.2.0.
Links. get_clip returns renderUrl (a signed link to the finished clip, valid for about an hour) and omits the raw source video link. analyze_clip_url omits the web's share-card signature (shareSig).
Refusals by code. render_clip's "already rendering" and every find_moments refusal (search pending, runs used, no speech, source not stored, video not ready, members only) are recognized by the API's stable code field, never by its localized text (src/render-hint.ts, src/find-moments-hint.ts). The members-only text names no plan or link.
Input validation. Every tool's arguments are validated with zod (src/args.ts, limits mirror packages/api-contract) before any request is sent; the web API validates again server-side, including the YouTube host allowlist for import_youtube.
Redirects. The client never follows redirects, so the key is only ever sent to CLIPAI_BASE_URL. A redirect is reported as a configuration error.
The key never comes back. Results and errors are scrubbed of the key.
Least privilege on the server side (#712): every API key acts with admin rights on the clip pipeline, so the web app refuses keys (web session only) for disconnecting social accounts and for campaign spend, in addition to key management, billing and connecting accounts.

YouTube import was removed from the iOS app only (App Review guideline 5.2.3); it remains available on the web and through this server by design.

CLIPAI_BASE_URL is validated at startup and the server exits with an error (rather than starting up misconfigured) if it is not:

an origin - scheme + host, no path. Request paths are absolute, so a base path would be silently discarded when they are resolved against it (https://host/clipai would quietly become https://host/api/...).
https, with localhost / 127.0.0.1 / [::1] allowed for local dev. The API key rides every request as a bearer token, so a plaintext origin would put it on the wire in the clear.

A value with no scheme at all (clipai.online, localhost:3000) is rejected the same way - include the scheme.

Quick start (npx)

The server is published to npm as clipai-mcp (requires Node >= 20). No clone or build needed.

Version note (2026-10-31): this folder is 0.3.0; npm serves 0.2.2 until 0.3.0 is published through publish-mcp.yml. 0.3.0 adds analyze_clip_url and find_moments. 0.2.3 detects "already rendering" from the 409's code field (alreadyRendering) instead of English error text, so a translated error still gets the wait-and-retry hint. 0.2.2 added mcpName for the MCP Registry; 0.2.1 added dub_consent (the API refuses a dub without it, so 0.2.0 cannot dub) and local id and dub_language checks; 0.2.0 (2026-10-08) added the annotations, untrusted-content envelope, zod validation, no-redirect client and key scrubbing.

{
  "mcpServers": {
    "clipai": {
      "command": "npx",
      "args": ["-y", "clipai-mcp"],
      "env": { "CLIPAI_API_KEY": "clip_xxxxxxxxxxxxxxxxxxxx" }
    }
  }
}

Build from source

cd apps/mcp
pnpm install     # from repo root (workspace) or here
pnpm build       # tsc -> dist/

Publishing

Preferred: GitHub Actions trusted publishing (no token, no OTP). npm is retiring 2FA-bypass publish tokens (GitHub changelog 2026-07-08), and trusted publishing (OIDC) is the supported automated path. Bump version in package.json, merge, then run Actions -> "Publish clipai-mcp" -> Run workflow on master (or push a tag mcp-v<version>). The workflow (.github/workflows/publish-mcp.yml) type-checks, runs the contract check, refuses to republish an existing version, builds via npm run release, and prints what npm serves. One-time setup on npmjs.com: package clipai-mcp -> Settings -> Trusted Publisher -> GitHub Actions, user isi1314, repository clipping-app, workflow publish-mcp.yml, allow npm publish; run the workflow within 2 days of saving or the configuration expires. No provenance badge while the repository is private.

Manual fallback (needs the npm account and its authenticator OTP):

Published as clipai-mcp on npm. Bump version in package.json when this package changes (the server reports that version to clients), then:

cd apps/mcp
npm whoami                    # must print the package owner; else `npm login`
npm run release -- --dry-run  # build, then a dry-run publish: no warnings expected
npm run release               # build, then publish (prompts for the OTP)
npm view clipai-mcp version bin   # confirm the version AND that bin survived

Always publish with npm run release, never a bare npm publish on a fresh checkout: npm 11 validates bin when it first reads package.json, before prepublishOnly runs, so with no dist/ yet it silently drops the clipai-mcp bin (npx clipai-mcp would then stop working). release builds first; the build also marks dist/index.js executable.

prepublishOnly wipes dist/, rebuilds with tsc and re-runs scripts/check-contract-enums.mjs (the hand-copied platform, layout, reframe_focus and goal enums in src/enums.ts must match packages/api-contract), so a stale or drifted build cannot ship. Two hand-copied values are not checked by that script: FIND_MOMENTS_TOPIC_MAX (apps/web/src/lib/moments.ts) and the score band thresholds in src/score-shape.ts (apps/web/src/lib/score-bands.ts).

Listing in the MCP Registry

server.json describes this package for the official MCP Registry (registry.modelcontextprotocol.io, schema 2025-12-11). The registry stores metadata only and installs from npm, so the npm version must exist first. The name is io.github.isi1314/clipai-mcp (a GitHub namespace, so no DNS record is needed; a online.clipai/* name can replace it later once a DNS TXT record is added). It has no repository field because the repository is private; websiteUrl points at https://clipai.online/mcp instead.

0.2.2 is on npm (2026-10-25, publish-mcp.yml). The listing runs in CI: Actions -> "Publish clipai-mcp to the MCP Registry" (publish-mcp-registry.yml) logs in with GitHub Actions OIDC, so no device-code sign-in is needed. The manual steps below remain the fallback.

To publish a new version by hand:

Bump version in package.json and both version fields in server.json (top level and packages[0]) to the same value.
Publish to npm as above. The registry checks that the published package.json carries "mcpName": "io.github.isi1314/clipai-mcp", so 0.2.1 and older cannot be listed; 0.2.2 is the first that can.
Install the publisher: brew install mcp-publisher, or the release binary from github.com/modelcontextprotocol/registry/releases.
cd apps/mcp && npm run check-server-json && mcp-publisher validate (the first checks names and versions against package.json offline, and prepublishOnly runs it too; the second checks the file against the live registry, publishes nothing).
mcp-publisher login github and sign in as isi1314 (the namespace owner).
mcp-publisher publish, then confirm: curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.isi1314/clipai-mcp".

The registry limits description to 100 characters.

Configure in Claude Desktop / Claude Code

Add to your MCP client config (e.g. Claude Desktop claude_desktop_config.json; in Claude Code, claude mcp add clipai --env CLIPAI_API_KEY=clip_... -- node <path>/dist/index.js):

{
  "mcpServers": {
    "clipai": {
      "command": "node",
      "args": ["<absolute path to the repo>/apps/mcp/dist/index.js"],
      "env": {
        "CLIPAI_API_KEY": "clip_xxxxxxxxxxxxxxxxxxxx",
        "CLIPAI_BASE_URL": "https://clipai.online"
      }
    }
  }
}

Then ask: "Clip this YouTube video to 9:16 with a hook, then schedule the best one to my TikTok." The agent will call the tools above in sequence.

Recipes

FilmCraft (skills/clipai-filmcraft/SKILL.md): a Claude Code skill that takes ClipAI's picks into a FilmCraft sequence over both MCP servers (place clips, import ClipAI's SRT captions, Auto Reframe, export the "Social Vertical 1080x1920" preset), either from list_clips with timeline.place, or from the FCPXML / OTIO / EDL export of a video (GET /api/videos/<id>/export?format=fcpxml, member plans). Install by copying the folder to ~/.claude/skills/clipai-filmcraft/.