smovie-mcp
Enables submitting TikTok URLs as download jobs, with options for immediate, queued, or scheduled downloads, audio-only or capped-resolution video, progress tracking, cancellation, retry, and retrieval of finished files.
Enables submitting YouTube URLs as download jobs, with options for immediate, queued, or scheduled downloads, audio-only or capped-resolution video, progress tracking, cancellation, retry, and retrieval of finished files.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@smovie-mcp download this TikTok video and save it when it's done: https://www.tiktok.com/@user/video/123"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
smovie
A small download service for YouTube and TikTok, built to run all the time on the Mac mini. You send it a URL, it adds a job to a queue (to run now, in turn, or at a set time), and yt-dlp downloads the video. You follow progress on a view-only dashboard, through the REST API, or through an MCP server that agents can use.
URL ──► POST /api/jobs ──► SQLite queue ──► worker (yt-dlp, N at a time) ──► data/downloads/<job>/
▲ │
dashboard (view) ──────┤ ▼
MCP server (agents) ───┘ GET /api/jobs/<id>/fileRun
uv sync
uv run smovie # http://localhost:8787 (dashboard) /docs (API)To install it on the mini so it starts at login and restarts if it crashes:
SM_API_TOKEN=change-me deploy/install-launchd.shRequires ffmpeg (brew install ffmpeg) to merge video and audio.
Settings (environment variables)
Var | Default | |
|
| DB, downloads, log |
|
| |
|
| parallel downloads |
| none | if set, API needs |
| none | Netscape cookies.txt, for YouTube "confirm you're not a bot" errors |
|
| where the MCP server finds the API |
Related MCP server: Importly MCP Server
API
Method | Path | |
POST |
|
|
GET |
| list jobs |
GET |
| status, progress, speed, eta, title, error |
GET |
| download the finished file |
POST |
| cancel a scheduled, queued or running job |
POST |
| requeue a failed or canceled job |
DELETE |
| remove job (and its file) |
GET |
|
when=now moves the job to the front of the queue (it still waits if all download slots are busy).
run_at without a timezone means the mini's local time.
curl -X POST localhost:8787/api/jobs -H 'content-type: application/json' \
-d '{"url":"https://www.tiktok.com/@user/video/123","when":"schedule","run_at":"2026-10-29T02:00"}'
curl -OJ localhost:8787/api/jobs/<id>/fileJobs that were downloading when the service stopped go back to the queue when it restarts.
Animation Studio (codex-3d)
"purpose": "depth" (or "action") on a job hands the finished file to Animation Studio, which polls for done jobs once a minute and
takes each in once (hardlinked, so deleting the job keeps its copy). "studio" carries its fields: id, name, rights, and
optionally window [start, end] in seconds with scene, for a depth reference of that window. Depth and action downloads are video, capped at 1080.
curl -X POST localhost:8787/api/jobs -H 'content-type: application/json' \
-d '{"url":"https://youtu.be/…","purpose":"depth","studio":{"id":"got-olenna","name":"Olenna","rights":"non-commercial reference"}}'Agents
MCP:
.mcp.jsonregisterssmovie-mcp(stdio). The tools aresubmit_video,wait_for_job,save_video,list_jobs,get_job,cancel_job,retry_jobanddelete_job. To use it from another machine, setSM_API_URL=http://<mini>.local:8787(andSM_API_TOKEN).Skill:
.claude/skills/video-download/SKILL.mdcovers the same flow with curl.
Maintenance
YouTube and TikTok change often, so keep yt-dlp up to date. Running deploy/update-ytdlp.sh weekly is enough.
Roadmap
Trimming: add
trim: {start, end}to the job options and runffmpeg -ss … -to … -c copyafter the download.Cloud: the same service in a container. Expect YouTube to block datacenter IPs, so plan on cookies or a residential proxy.
License
MIT, see LICENSE. Only download content you have the right to; downloading may break YouTube's and TikTok's terms of service.
Available Tools
8 toolscancel_jobC
Cancel a scheduled, queued or running job.
Inputs: job_id (required).
delete_jobB
Remove a job from the list, and its file from the server unless delete_file is false.
Inputs: job_id (required), delete_file.
get_jobC
Get one job: status, progress %, speed, title, filename, error.
Inputs: job_id (required).
list_jobsA
List recent jobs, newest first. status filters by comma-separated states: scheduled, queued, downloading, done, failed, canceled.
Inputs: limit, status.
retry_jobA
Put a failed or canceled job back in the queue.
Inputs: job_id (required).
save_videoB
Copy a finished job's file from the service to a local folder. Returns the saved path.
Inputs: job_id (required), dest_dir.
submit_videoA
Add a YouTube or TikTok URL to the download queue.
when: "now" jumps the queue, "queue" waits its turn, "schedule" starts at run_at
(ISO 8601, e.g. "2026-10-29T02:00"; no timezone = the server's local time).
max_height caps resolution (e.g. 1080). Returns the job, including its id.
purpose: "depth" (or "action") hands the finished file to Animation Studio (codex-3d), which picks up
done jobs by itself; studio carries its fields: id, name, rights, and optionally window [start, end]
in seconds and scene (then a depth reference is made for that window).
Inputs: url (required), when, run_at, studio, +3 more.
wait_for_jobC
Wait until a job is done, failed or canceled (or the timeout passes) and return it.
Inputs: job_id (required), timeout_seconds.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool has a clearly distinct role across the job lifecycle: submit, inspect, list, wait, save, cancel, retry, and delete. The nearest pair, get_job and wait_for_job, is differentiated by wait_for_job blocking until a terminal state or timeout.
All eight tools follow a consistent snake_case verb_noun pattern (get_job, submit_video, list_jobs, wait_for_job, save_video, cancel_job, retry_job, delete_job). No mixed casing or inconsistent verb styles appear.
Eight tools is well-scoped for a video download queue service, covering submission, monitoring, waiting, file retrieval, and lifecycle management without bloat. Each tool earns its place in the workflow.
The surface covers the full job lifecycle: create/submit, get, list, wait, save finished files, cancel, retry, and delete. Scheduling and Animation Studio handoff are handled through submit_video, leaving no obvious dead ends for the stated purpose.
Maintenance
Related MCP Connectors
Download video and audio from public media URLs, or extract their metadata, with one async REST API.
Turn any video or audio link into files, transcripts and metadata, right from your AI agent.
Youtube Download API: Download audio and video from YouTube. On the JoJ API marketplace.
YouTube transcripts, search, channel/playlist listings and upload tracking for AI agents.
Related MCP Servers
- -licenseAqualityNot gradedmaintenanceEnables downloading videos from 1000+ platforms including YouTube, Bilibili, TikTok, and Twitter using yt-dlp. Supports both MCP protocol and REST API modes with real-time progress tracking, multiple formats, and subtitle downloads.514 npm1-
- AlicenseAqualityCmaintenanceEnables AI agents to download, transcribe, and read metadata for any video or audio URL - YouTube, TikTok, X, podcasts and 1000+ sites - working from agent sandboxes and servers where direct downloads usually get blocked. $3 free credit, no card.928 npmMIT
- AlicenseAqualityCmaintenanceEnables AI agents to create, monitor, and download video transcodes through the FFmpeg Micro REST API.11140 npm1MIT

clipsdk-mcpofficial
AlicenseNot gradedqualityCmaintenanceEnables coding agents to turn long videos into captioned short clips, upload local or linked media, monitor jobs, and save finished MP4s with titles, scores, and ready-to-post captions to disk.MIT