Lumiclip

Official

by lumiclip · TypeScript

Turn YouTube videos into short-form clips from any AI assistant

Convert YouTube videos into short-form clips automatically.

README.md9 KBView on GitHub

@lumiclip/mcp-server

Turn long videos into short clips — from Claude, Cursor, or any AI assistant that supports MCP.

Give it a YouTube link. It finds the best moments, reframes for vertical video (9:16), adds subtitles, and returns download-ready clips.

Quick Start

Get an API key at app.lumiclip.ai/developers
Run:

bash

LUMICLIP_API_KEY=sk_live_... npx @lumiclip/mcp-server

Setup

Claude Desktop / Cursor

Add to your config file — claude_desktop_config.json for Claude, .cursor/mcp.json for Cursor:

json

{
  "mcpServers": {
    "lumiclip": {
      "command": "npx",
      "args": ["@lumiclip/mcp-server"],
      "env": {
        "LUMICLIP_API_KEY": "sk_live_..."
      }
    }
  }
}

Cursor Directory

Install in Cursor

Smithery

bash

npx @smithery/cli mcp add lumiclip/lumiclip

Remote (Streamable HTTP)

For n8n, custom integrations, or any client that supports remote MCP:

Endpoint: https://mcp.lumiclip.ai/mcp
Auth: Authorization: Bearer sk_live_...
Transport: Streamable HTTP (POST)

Tools

Tool	What it does
`generate_clips`	Start clip generation from a YouTube URL. Returns a `project_id` right away.
`get_project_status`	Check progress and get clips when ready. Clips are sorted by score (best first).
`list_projects`	List your projects with status and clip counts.
`get_clip`	Get full details for a single clip.
`check_usage`	See your plan, remaining credits, and usage.

How It Works

Call generate_clips with a YouTube URL
Get back a project_id immediately
Poll get_project_status every 10–15 seconds (or pass a callback_url for webhook)
When done, clips are sorted by score (best first), each with a download_url

Statuses

Project: pending → processing → completed (or completed_no_clips / failed)

Processing steps: queued → DOWNLOADING_VIDEO → EXTRACTING_AUDIO → TRANSCRIBING → DETECTING_HIGHLIGHTS → CUTTING_CLIPS → EXPORTING_CLIPS → done

Clips: pending → exporting → completed (or failed). The download_url is available when clip_status is completed.

API Reference

`generate_clips`

Start clip generation from a YouTube video.

Field	Type	Required	Description
`url`	string	Yes	Full YouTube video URL
`start_time`	number	No	Start time in seconds (to process only a segment)
`end_time`	number	No	End time in seconds (to process only a segment)
`callback_url`	string	No	Webhook URL to receive results when done

json

{
  "project_id": "43dbe622-8ac6-4579-9625-0ad7f0f9db0b",
  "status": "processing",
  "poll_url": "/api/v1/projects/43dbe622-8ac6-4579-9625-0ad7f0f9db0b",
  "estimated_minutes": 5,
  "message": "Processing started. Poll with get_project_status every 10-15 seconds until status is 'completed'."
}

`get_project_status`

Check progress and get clips.

Field	Type	Required	Description
`project_id`	string	Yes	The project ID from `generate_clips`

json

{
  "id": "43dbe622-...",
  "name": "Video Title",
  "status": "completed",
  "step": "done",
  "error": null,
  "expected_clips": 9,
  "duration": 639,
  "created_at": "2026-03-15T02:21:46.226Z",
  "clips": [
    {
      "id": "32538b9c-...",
      "title": "One Dating Theory Leads to Chaos",
      "duration": 41.83,
      "score": 90,
      "reason": "Sharp universal joke that hooks instantly with strong reactions.",
      "clip_status": "completed",
      "download_url": "https://cdn.lumiclip.ai/exports/premium/.../clip-32538b9c-....mp4",
      "quality": "1080p",
      "thumbnail_url": "https://cdn.lumiclip.ai/exports/premium/.../clip-32538b9c-...-thumb.jpg",
      "created_at": "2026-03-15T02:29:10.954Z",
      "updated_at": "2026-03-15T02:30:43.907Z"
    }
  ]
}

Clips are sorted by score (highest first).

`list_projects`

Field	Type	Required	Description
`limit`	number	No	Max projects to return. Default 20, max 100.
`status`	string	No	Filter: `pending`, `processing`, `completed`, `completed_no_clips`, `failed`

json

{
  "projects": [
    {
      "id": "43dbe622-...",
      "name": "Video Title",
      "status": "completed",
      "step": "done",
      "expected_clips": 9,
      "clips_count": 8,
      "duration": 639,
      "created_at": "2026-03-15T02:21:46.226Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

`get_clip`

Field	Type	Required	Description
`clip_id`	string	Yes	The clip ID from a project's clips array

json

{
  "id": "32538b9c-...",
  "project_id": "43dbe622-...",
  "title": "One Dating Theory Leads to Chaos",
  "duration": 41.83,
  "score": 90,
  "reason": "Sharp universal joke that hooks instantly.",
  "export_status": "completed",
  "export_quality": "1080p",
  "is_exported": true,
  "video_url": "https://cdn.lumiclip.ai/...",
  "video_url_720p": "https://cdn.lumiclip.ai/...",
  "video_url_1080p": "https://cdn.lumiclip.ai/...",
  "thumbnail_url": "https://cdn.lumiclip.ai/...",
  "created_at": "2026-03-15T02:29:10.954Z",
  "updated_at": "2026-03-15T02:30:43.907Z"
}

`check_usage`

No input required.

json

{
  "plan": "pro",
  "credits_remaining": 450,
  "credits_total": 500,
  "period_start": "2026-03-01T00:00:00.000Z",
  "period_end": "2026-04-01T00:00:00.000Z"
}

Errors

HTTP Status	Error	What to do
400	Invalid YouTube URL	Check the URL format
401	Unauthorized	Check your API key
402	Insufficient credits	Buy more credits or use a shorter video
429	Rate limit exceeded	Wait and try again
500	Internal server error	Try again later

Webhooks

Pass a callback_url when calling generate_clips to receive a POST when all clips are ready.

Completed:

json

{
  "event": "project.completed",
  "project_id": "43dbe622-...",
  "status": "completed",
  "source_url": "https://www.youtube.com/watch?v=H51iLa1leOU",
  "clips": [
    {
      "id": "32538b9c-...",
      "title": "One Dating Theory Leads to Chaos",
      "duration": 41.83,
      "score": 90,
      "download_url": "https://cdn.lumiclip.ai/exports/premium/.../clip-32538b9c-....mp4",
      "thumbnail_url": "https://cdn.lumiclip.ai/exports/premium/.../clip-32538b9c-...-thumb.jpg",
      "quality": "1080p"
    }
  ]
}

Failed:

json

{
  "event": "project.failed",
  "project_id": "43dbe622-...",
  "status": "failed",
  "error": "YouTube video is unavailable",
  "clips": []
}

Clips are sorted by score (highest first). We retry up to 3 times if your server doesn't respond.

Signature verification (optional): Each callback includes an X-Lumiclip-Signature header. Compute HMAC-SHA256 of the request body using SHA-256(your_api_key) as the signing key. Compare with the header value (sha256=<hex>).

Using with n8n

Option A — Webhook (recommended):

Create a workflow with a Webhook trigger node. Copy its URL.
Add an HTTP Request node: POST https://api.lumiclip.ai/api/v1/clips/generate with Header Auth (Authorization: Bearer sk_live_...) and body:
json
```
{
  "url": "https://www.youtube.com/watch?v=...",
  "callback_url": "https://your-n8n.com/webhook/abc123"
}
```
When clips are ready, the Webhook node receives the payload.
Best clip: {{ $json.clips[0].download_url }}

Option B — Polling loop:

POST to generate clips (same as above, without callback_url).
Wait 15 seconds → GET https://api.lumiclip.ai/api/v1/projects/{{ $json.project_id }} → IF status is not completed, loop back to Wait.

REST API

For direct HTTP calls without MCP:

Method	Endpoint	Description
`POST`	`/api/v1/clips/generate`	Start clip generation
`GET`	`/api/v1/projects/:id`	Get project status and clips
`GET`	`/api/v1/projects`	List projects
`GET`	`/api/v1/clips/:id`	Get single clip details
`GET`	`/api/v1/account/usage`	Check credits and plan

Base URL: https://api.lumiclip.ai — All endpoints require Authorization: Bearer sk_live_...

Environment Variables

Variable	Required	Default
`LUMICLIP_API_KEY`	Yes	—
`LUMICLIP_API_URL`	No	`https://api.lumiclip.ai`

License

MIT

Install

Configuration

Environment variables

LUMICLIP_API_KEYrequiredsecret

Your Lumiclip API key from app.lumiclip.ai/developers

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "lumiclip": {
      "command": "npx",
      "args": [
        "-y",
        "@lumiclip/mcp-server@3.0.0"
      ],
      "env": {
        "LUMICLIP_API_KEY": "<YOUR_LUMICLIP_API_KEY>"
      }
    }
  }
}

@lumiclip/mcp-server

Quick Start

Setup

Claude Desktop / Cursor

Cursor Directory

Smithery

Remote (Streamable HTTP)

Tools

How It Works

Statuses

API Reference

generate_clips

get_project_status

list_projects

get_clip

check_usage

Errors

Webhooks

Using with n8n

REST API

Environment Variables

Links

License

Install

Configuration

`generate_clips`

`get_project_status`

`list_projects`

`get_clip`

`check_usage`