yt-curator 🎬🧹

YouTube playlist curation engine — inventory, deduplicate, merge, clean up, and reorganise thousands of playlists spanning 20 years.

hljs language-scss

┌────────────────────────────────────────────────────┐
│                   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

Three Interfaces

1. CLI (`yt-curator`)

hljs language-bash

# 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-mcp

2. MCP Server (`yt-curator-mcp`)

stdio mode (default — plug-and-play with Claude Desktop):

hljs language-json

{
  "mcpServers": {
    "yt-curator": {
      "command": "yt-curator",
      "args": ["serve-mcp"]
    }
  }
}

SSE mode (register with the mcp-gateway):

hljs language-bash

yt-curator serve-mcp --host 0.0.0.0 --port 39401

Then add to your gateway config:

hljs language-yaml

backends:
  - name: yt-curator
    type: sse
    url: http://127.0.0.1:39401

Available MCP tools:

Tool	Description
`list_playlists()`	List all playlists in the inventory DB
`get_playlist_contents(id)`	List all videos in a specific playlist with status
`scan_inventory()`	Full scan — all playlists, items, and video status
`curation_report()`	Summary stats from inventory
`find_duplicates(min=2)`	Cross-playlist duplicate detection
`find_dead_videos()`	Dead/private/blocked videos
`find_empty_playlists()`	Zero-video playlists
`suggest_merges()`	Title-similarity merge candidates
`merge_playlists(src, dst, dry_run=True)`	Merge with dry-run mode
`delete_playlist(id, dry_run=True)`	Delete with dry-run mode
`remove_dead_videos(dry_run=True)`	Bulk dead video removal
`auth_status()`	Check OAuth credentials

3. Python Library (`import yt_curator`)

hljs language-python

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
`playlists.list`	1	~18 calls
`playlistItems.list`	1	~900 calls
`videos.list` (status check)	1	~120 calls
`playlists.insert` / `.update`	50	per operation
`playlistItems.insert` / `.delete`	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.json
Run yt-curator auth — opens a browser for Google login

Tip for headless servers: Run yt-curator auth once on a desktop machine with a browser, then copy ~/.config/yt-curator/token.json to the server.

NixOS Module

Add yt-curator to your flake inputs:

hljs language-nix

{
  inputs.yt-curator = {
    url = "github:telos-systems/yt-curator";
    inputs.nixpkgs.follows = "nixpkgs";
  };
}

Then enable the module:

hljs language-nix

{
  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:

hljs language-bash

nix run github:telos-systems/yt-curator -- inventory
nix run github:telos-systems/yt-curator#mcp -- serve-mcp

Project Structure

hljs language-bash

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.md

Why 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

yt-curator 🎬🧹

YouTube playlist curation engine — inventory, deduplicate, merge, clean up, and reorganise thousands of playlists spanning 20 years.

hljs language-scss

┌────────────────────────────────────────────────────┐
│                   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

Three Interfaces

1. CLI (`yt-curator`)

hljs language-bash

# 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-mcp

2. MCP Server (`yt-curator-mcp`)

stdio mode (default — plug-and-play with Claude Desktop):

hljs language-json

{
  "mcpServers": {
    "yt-curator": {
      "command": "yt-curator",
      "args": ["serve-mcp"]
    }
  }
}

SSE mode (register with the mcp-gateway):

hljs language-bash

yt-curator serve-mcp --host 0.0.0.0 --port 39401

Then add to your gateway config:

hljs language-yaml

backends:
  - name: yt-curator
    type: sse
    url: http://127.0.0.1:39401

Available MCP tools:

Tool	Description
`list_playlists()`	List all playlists in the inventory DB
`get_playlist_contents(id)`	List all videos in a specific playlist with status
`scan_inventory()`	Full scan — all playlists, items, and video status
`curation_report()`	Summary stats from inventory
`find_duplicates(min=2)`	Cross-playlist duplicate detection
`find_dead_videos()`	Dead/private/blocked videos
`find_empty_playlists()`	Zero-video playlists
`suggest_merges()`	Title-similarity merge candidates
`merge_playlists(src, dst, dry_run=True)`	Merge with dry-run mode
`delete_playlist(id, dry_run=True)`	Delete with dry-run mode
`remove_dead_videos(dry_run=True)`	Bulk dead video removal
`auth_status()`	Check OAuth credentials

3. Python Library (`import yt_curator`)

hljs language-python

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
`playlists.list`	1	~18 calls
`playlistItems.list`	1	~900 calls
`videos.list` (status check)	1	~120 calls
`playlists.insert` / `.update`	50	per operation
`playlistItems.insert` / `.delete`	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.json
Run yt-curator auth — opens a browser for Google login

Tip for headless servers: Run yt-curator auth once on a desktop machine with a browser, then copy ~/.config/yt-curator/token.json to the server.

NixOS Module

Add yt-curator to your flake inputs:

hljs language-nix

{
  inputs.yt-curator = {
    url = "github:telos-systems/yt-curator";
    inputs.nixpkgs.follows = "nixpkgs";
  };
}

Then enable the module:

hljs language-nix

{
  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:

hljs language-bash

nix run github:telos-systems/yt-curator -- inventory
nix run github:telos-systems/yt-curator#mcp -- serve-mcp

Project Structure

hljs language-bash

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.md

Why 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)

yt-curator

yt-curator 🎬🧹

Features

Three Interfaces

1. CLI (`yt-curator`)

2. MCP Server (`yt-curator-mcp`)

3. Python Library (`import yt_curator`)

Quota Budget

Setup

One-time: Google Cloud + OAuth

NixOS Module

Project Structure

Why This Exists

Roadmap

License

Similar Packages

yt-curator

yt-curator 🎬🧹

Features

Three Interfaces

1. CLI (`yt-curator`)

2. MCP Server (`yt-curator-mcp`)

3. Python Library (`import yt_curator`)

Quota Budget

Setup

One-time: Google Cloud + OAuth

NixOS Module

Project Structure

Why This Exists

Roadmap

License

Similar Packages

yt-curator

yt-curator 🎬🧹

Features

Three Interfaces

1. CLI (yt-curator)

2. MCP Server (yt-curator-mcp)

3. Python Library (import yt_curator)

Quota Budget

Setup

One-time: Google Cloud + OAuth

NixOS Module

Project Structure

Why This Exists

Roadmap

License

Similar Packages

yt-curator

yt-curator 🎬🧹

Features

Three Interfaces

1. CLI (yt-curator)

2. MCP Server (yt-curator-mcp)

3. Python Library (import yt_curator)

Quota Budget

Setup

One-time: Google Cloud + OAuth

NixOS Module

Project Structure

Why This Exists

Roadmap

License

Similar Packages

1. CLI (`yt-curator`)

2. MCP Server (`yt-curator-mcp`)

3. Python Library (`import yt_curator`)

1. CLI (`yt-curator`)

2. MCP Server (`yt-curator-mcp`)

3. Python Library (`import yt_curator`)