yt-curator-mcp
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., "@yt-curator-mcp scan my YouTube inventory for duplicates"
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.
yt-curator π¬π§Ή
YouTube playlist curation engine β inventory, deduplicate, merge, clean up, and reorganise thousands of playlists spanning 20 years.
ββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β yt-curator β
β β
β βββββββββββ βββββββββββ ββββββββββββββββββββββ β
β β CLI β β MCP β β Python Library β β
β β (Click)β β (FastMCP)β β (import yt_curator)β β
β ββββββ¬βββββ ββββββ¬βββββ βββββββββββ¬βββββββββββ β
β β β β β
β ββββββββ¬ββββββββββββββββββββββββ β
β β β
β ββββββββββΌβββββββββ β
β β YouTube Data β β
β β API v3 + OAuthβ β
β β + Local SQLite β β
β βββββββββββββββββββ β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββFeatures
Full inventory β scan all your playlists and every video in them into a local SQLite database
Dead video detection β find deleted, private, and blocked videos across all playlists
Cross-playlist deduplication β find every video that appears in 2+ playlists
Intra-playlist dedup β remove duplicate copies within a single playlist
Merge playlists β move all videos from one playlist into another, then delete the source
Bulk delete β remove empty or unwanted playlists
Merge suggestions β AI-free title-similarity analysis to find consolidation candidates
Privacy audit β see which playlists are public vs private
Dry-run everything β all destructive operations preview before executing
Related MCP server: YouTube MCP Server
Three Interfaces
1. CLI (yt-curator)
# OAuth setup (one-time)
yt-curator auth
# Full inventory scan
yt-curator inventory
# Reports
yt-curator report
yt-curator find-dupes
yt-curator find-dead
# Curation (try --dry-run first!)
yt-curator merge PL_source_id PL_target_id --dry-run
yt-curator dedup PL_playlist_id --dry-run
yt-curator delete PL_playlist_id --dry-run
# Start MCP server
yt-curator serve-mcp2. MCP Server (yt-curator-mcp)
Register as a backend for any MCP client (Claude Desktop, Hermes, Cursor, etc.).
stdio mode (default β plug-and-play with Claude Desktop):
{
"mcpServers": {
"yt-curator": {
"command": "yt-curator",
"args": ["serve-mcp"]
}
}
}SSE mode (register with the mcp-gateway):
yt-curator serve-mcp --host 0.0.0.0 --port 39401Then add to your gateway config:
backends:
- name: yt-curator
type: sse
url: http://127.0.0.1:39401Available MCP tools:
Tool | Description |
| List all playlists in the inventory DB |
| List all videos in a specific playlist with status |
| Full scan β all playlists, items, and video status |
| Summary stats from inventory |
| Cross-playlist duplicate detection |
| Dead/private/blocked videos |
| Zero-video playlists |
| Title-similarity merge candidates |
| Merge with dry-run mode |
| Delete with dry-run mode |
| Bulk dead video removal |
| Check OAuth credentials |
3. Python Library (import yt_curator)
from yt_curator.core.client import YouTubeClient
from yt_curator.core.inventory import scan_all
client = YouTubeClient()
report = scan_all(client)
print(f"Scanned {report.total_playlists} playlists")Quota Budget
YouTube Data API v3 default: 10,000 units/day (free).
Operation | Cost per call | Your 900-playlist scan |
| 1 | ~18 calls |
| 1 | ~900 calls |
| 1 | ~120 calls |
| 50 | per operation |
| 50 | per operation |
Full inventory scan | ~1,200 units β |
A full scan uses ~12% of your daily quota, leaving 8,800 units for curation writes (about 175 write operations per day).
Setup
One-time: Google Cloud + OAuth
Go to Google Cloud Console
Create a project β Enable YouTube Data API v3
APIs & Services β Credentials β Create Credentials β OAuth client ID
Application type: Desktop app
Download
client_secret.json
Save it to
~/.config/yt-curator/client_secret.jsonRun
yt-curator authβ opens a browser for Google login
Tip for headless servers: Run
yt-curator authonce on a desktop machine with a browser, then copy~/.config/yt-curator/token.jsonto the server.
NixOS Module
Add yt-curator to your flake inputs:
{
inputs.yt-curator = {
url = "github:telos-systems/yt-curator";
inputs.nixpkgs.follows = "nixpkgs";
};
}Then enable the module:
{
imports = [ yt-curator.nixosModules.default ];
services.yt-curator = {
enable = true;
mcpServer.enable = true;
mcpServer.port = 39401;
credentials.clientSecretPath = config.sops.secrets."yt-curator/client_secret".path;
};
}Or use the flake directly:
nix run github:telos-systems/yt-curator -- inventory
nix run github:telos-systems/yt-curator#mcp -- serve-mcpProject Structure
yt-curator/
βββ src/yt_curator/
β βββ __init__.py # Package entry
β βββ cli/app.py # Click CLI (11 commands)
β βββ mcp/server.py # FastMCP server (12 tools)
β βββ core/
β β βββ auth.py # OAuth 2.0 + token storage
β β βββ client.py # YouTube API client wrapper
β β βββ inventory.py # Full scan β SQLite
β β βββ curator.py # Merge, delete, dedup operations
β β βββ dedup.py # Cross-playlist dedup + suggestions
β β βββ __init__.py # Data models (dataclasses)
β βββ db/schema.py # SQLite schema
βββ nix/module.nix # NixOS module
βββ flake.nix # Nix flake
βββ pyproject.toml # Python project metadata
βββ LICENSE # MIT
βββ README.mdWhy This Exists
YouTube's web UI has no bulk operations. If you have 900+ playlists accumulated over 20 years, there's no way to:
Find which videos are dead across all playlists
See which videos appear in 10 different playlists
Merge similar playlists
Delete 50 empty playlists in one go
Existing MCP servers for YouTube are read-only analytics tools or basic CRUD wrappers. None do inventory, dedup, merge, or bulk curation. This fills that gap.
Roadmap
Core: inventory, dedup, merge, delete, dead video removal
CLI: 11 commands with --dry-run
MCP server: 12 tools (stdio + SSE)
Nix flake + NixOS module
AI-assisted reorganisation (local LLM via Ollama)
Playlist-as-code (declarative YAML β desired state)
GitHub release + PyPI publish
Scheduled inventory drift detection (weekly cron)
License
MIT Β© 2026 Telos Systems / Danny Poulson
Available Tools
12 toolsauth_statusA
Check whether OAuth credentials are configured and valid.
Inputs: no named parameters. Returns: result
curation_reportA
Generate a summary report from the inventory database.
Shows playlist/video counts, dead videos, duplicates, and empty playlists.
Requires that scan_inventory() has been run first.
Inputs: db_path. Returns: result
delete_playlistA
Delete a playlist and all its contents.
By default runs in dry_run mode β set dry_run=False to actually delete.
Args: playlist_id: The YouTube playlist ID to delete (e.g. PL...) dry_run: If True (default), only preview; set False to execute
Inputs: playlist_id (required), db_path, dry_run. Returns: result
find_dead_videosB
Find deleted, private, or blocked videos across all playlists.
Inputs: db_path. Returns: result
find_duplicatesA
Find videos that appear in multiple playlists.
Args: min_appearances: Minimum number of playlists a video must appear in (default: 2, meaning any duplication at all).
Inputs: db_path, min_appearances. Returns: result
find_empty_playlistsB
Find playlists with 0 videos.
Inputs: db_path. Returns: result
get_playlist_contentsB
List all videos in a specific playlist.
Inputs: playlist_id (required), db_path. Returns: result
list_playlistsA
List all playlists in the inventory database.
Run scan_inventory() first if the database is empty.
Inputs: db_path. Returns: result
merge_playlistsA
Move all videos from the SOURCE playlist into the TARGET, then delete SOURCE.
Skips videos already present in the target. By default runs in dry_run mode β set dry_run=False to actually execute.
Args: source_id: Playlist ID to move videos from (e.g. PL...) target_id: Playlist ID to move videos into dry_run: If True (default), only preview; set False to execute
Inputs: source_id (required), target_id (required), db_path, dry_run. Returns: result
remove_dead_videosA
Remove all dead/private/blocked videos from their playlists.
By default runs in dry_run mode β set dry_run=False to actually remove.
Args: dry_run: If True (default), only preview; set False to execute
Inputs: db_path, dry_run. Returns: result
scan_inventoryA
Run a full inventory scan: list all playlists, all items, check video status.
This is the primary data-collection command. Run this first before any curation operations. Uses the YouTube Data API β consumes ~1,200 quota units for a typical 900-playlist account.
Inputs: db_path, read_only. Returns: result
suggest_mergesA
Suggest playlist merge candidates based on title similarity.
Useful for consolidating fragmented playlists (e.g. "Tech 2020" + "Tech 2021").
Inputs: db_path. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 12 tools
Most tools target distinct resources/actions, but list_playlists and scan_inventory overlap slightly since both return playlist lists; the descriptions clarify that scan_inventory is the primary data-collection command. Overall, boundaries are clear.
The set mostly follows a verb_noun pattern (list_*, get_*, find_*, merge_*, delete_*, remove_*). Exceptions like 'curation_report' and 'auth_status' are minor and still readable, so consistency is good but not perfect.
With 12 tools, the server is well-scoped for a playlist curation domain. Each tool earns its place, covering inventory scanning, analysis, and actionable curation without unnecessary bloat.
The surface covers the full curation workflow: scan, analyze, merge, delete, and remove dead videos. Minor gaps exist (e.g., no playlist creation/renaming or single-video moves), but these are peripheral to the core purpose.
Maintenance
Related MCP Connectors
Hosted MCP for YouTube Studio: uploads, metadata, playlists, comments, analytics, captions.
Unofficial YouTube MCP β wraps the YouTube Data API v3 (BYO API key)
Your YouTube library, in the AI tools you already use: Claude, ChatGPT, Cursor, any MCP client.
Real-time YouTube transcripts, comments, channels & video search MCP. Local npx or hosted OAuth.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server for organizing YouTube playlists via the YouTube Data API v3, enabling playlist and playlist item creation, listing, updating, and deletion through natural language.9MIT
- AlicenseNot gradedqualityDmaintenanceEnables MCP clients to search and read YouTube data and safely manage playlists, including creating private playlists from ranked song matches with preview-before-commit playlist mutations.1Apache 2.0
- FlicenseNot gradedqualityCmaintenanceEnables AI coding tools and MCP hosts to search YouTube Music and add or remove tracks on your own playlists through natural-language prompts, authenticated with your Google login. It runs locally over stdio, so credentials and OAuth tokens stay on your machine.-
- FlicenseBqualityBmaintenanceEnables users to identify, classify, deduplicate, and save YouTube/YouTube Music tracks into their own YouTube playlists, with legacy Spotify playlist tools also available.15-