mcp-youtube
Provides tools for managing YouTube playlists, including searching, listing, creating, adding to, pruning, and deleting playlists through the YouTube Data API v3.
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., "@mcp-youtube Clean up tombstones and duplicates in my 'Favorites' playlist."
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.
▶️ MCP server for the full YouTube Data API v3 — playlists, videos, channels, community, captions, and media, conversationally from any MCP client
Website · Documentation
Features
Full YouTube Data API v3 coverage — 52 tools spanning playlists, videos, channels & sections, subscriptions, comments, captions, thumbnails, watermarks, playlist cover images, and read-only reference data, all under the
youtube.force-sslscopeQuota-aware by design — every tool documents its cost up front, from 1-unit reads to the 1600-unit
upload-videoGuarded destructive actions — every delete, unsubscribe, moderation action, or other irreversible/outward tool refuses to run without
confirm: trueFull-replace done safely — YouTube's
updatemethods overwrite an entire resource part; tools likeupdate-video,update-playlist,update-channel, andupdate-channel-sectionread the current resource first so an update that only changes one field never silently blanks the restSafe bulk cleanup —
clean-playlistscans for[Deleted video]/[Private video]tombstones, duplicates, and videos from named channels, then defaults to a dry run so you see the plan before anything is removedLocal-file media uploads — videos, captions, thumbnails, watermarks, and playlist cover images all upload from a local file path via resumable upload where the API requires it
One-time OAuth setup — a desktop-flow
npm run setuphandles Google authorisation and prints a refresh token; you supply it (and the client id/secret) to the server via environment variables, from any store you likeTyped end to end — Zod-validated tool schemas and a Vitest suite covering every handler
Related MCP server: YouTube MCP Server
Install
The server works with any MCP-compatible client — Claude Desktop, Claude Code, Cursor, Cline, Zed, Continue, and others.
Install the package:
npm install -g @kud/mcp-youtubeIn Claude Code or Claude Desktop you can instead install it as a plugin, which wires up the registration for you:
/plugin install youtube@kudEither way, run the one-time OAuth setup before first use:
npm run setupThis walks you through creating a Google Cloud OAuth client (Desktop app type), opens a browser to authorise the youtube.force-ssl scope, and prints the resulting credentials — it writes nothing to disk. Stash them wherever you keep secrets (keychain, secrets manager, your MCP client's env block) and expose them to the server as environment variables:
Variable | Holds |
| OAuth client ID |
| OAuth client secret |
| long-lived refresh token |
The server reads these three from the environment only — it's store-agnostic, so how they get there is up to you. A keychain-backed export works well:
export MCP_YOUTUBE_REFRESH_TOKEN=$(security find-generic-password -s mcp-youtube-refresh-token -w)Tip: set the OAuth app's publishing status to In production in Google Cloud.
youtube.force-sslis a sensitive scope, and while the app sits in Testing the refresh token expires after 7 days.
Configuration
Register the server with your MCP client. The exact config file and its location depend on the client — Claude Desktop, for example, uses claude_desktop_config.json (Settings → Developer → Edit Config); Cursor, Cline, Zed, and Continue each have their own. The registration follows the standard mcpServers shape:
{
"mcpServers": {
"youtube": {
"command": "npx",
"args": ["-y", "@kud/mcp-youtube"],
"env": {
"MCP_YOUTUBE_CLIENT_ID": "your-client-id",
"MCP_YOUTUBE_CLIENT_SECRET": "your-client-secret",
"MCP_YOUTUBE_REFRESH_TOKEN": "your-refresh-token"
}
}
}
}If you installed via /plugin install youtube@kud, the plugin handles registration — you only need to supply the three environment variables above.
Usage
YouTube's Data API v3 gives every project a fixed 10,000 quota units/day. A single careless search, bulk delete, or video upload can burn through a meaningful chunk of that, so every tool documents its cost up front — and every destructive or outward-irreversible tool requires an explicit confirm: true.
52 tools cover the full read/write surface reachable under the youtube.force-ssl scope:
Category | Tools | Docs |
Searching |
| |
Playlists |
| |
Cleaning |
| |
Deleting |
| |
Videos |
| |
Channels & sections |
| |
Community |
| |
Captions & media |
| |
Reference data |
|
Once installed, just ask your MCP client:
> Clean up the tombstones in my "Focus" playlist
Scanned 214 items — found 6 tombstones ([Deleted video]/[Private video]).
This is a dry run, no changes made. Estimated cost to delete: 300 units.
Want me to go ahead?
> Yes, and dedupe it too
Deleted 6 tombstones and 3 duplicates (9 items, 450 units).clean-playlist always returns its plan first — pass dryRun: false (or just confirm in conversation) to actually delete.
Development
git clone https://github.com/kud/mcp-youtube.git
cd mcp-youtube
npm install
npm run devScript | Purpose |
| Run the server directly from source ( |
| Compile to |
| Run the Vitest suite |
| Type-check without emitting |
| Launch the MCP Inspector against source |
📚 Full documentation → mcp-youtube/docs
Available Tools
52 toolsadd-to-playlistA
Add one or more videos to a playlist. Costs 50 quota units per video.
Inputs: videoIds (required), playlistId (required).
clean-playlistA
Scan a playlist (1 unit/page) and plan removal of [Deleted video]/[Private video] tombstones, duplicates, and/or videos from given channels. Defaults to dry-run (dryRun: true) — returns the plan without deleting. Pass dryRun: false to actually delete, at 50 quota units per item.
Inputs: playlistId (required), dedupe, dryRun, pruneChannelIds, +1 more.
create-channel-sectionA
Create a new channel section (homepage shelf). Costs 50 quota units.
Inputs: type (required), style, title, position, +2 more.
create-comment-threadA
Post a new top-level comment on a video or channel. Costs 50 quota units.
Inputs: text (required), videoId, channelId.
create-playlistB
Create a new playlist. Costs 50 quota units.
Inputs: title (required), description, privacyStatus.
delete-captionA
Permanently delete a caption track. Costs 50 quota units. Requires confirm: true.
Inputs: captionId (required), confirm.
delete-channel-sectionA
Permanently delete a channel section. Costs 50 quota units. Requires confirm: true.
Inputs: channelSectionId (required), confirm.
delete-commentA
Permanently delete a comment. Costs 50 quota units. Requires confirm: true.
Inputs: commentId (required), confirm.
delete-playlistA
Permanently delete an entire playlist. Costs 50 quota units. Requires confirm: true.
Inputs: playlistId (required), confirm.
delete-playlist-imageA
Permanently delete a playlist cover image. Costs 50 quota units. Requires confirm: true.
Inputs: playlistImageId (required), confirm.
delete-videoA
Permanently delete a video you own. Costs 50 quota units. Requires confirm: true.
Inputs: videoId (required), confirm.
download-captionB
Download a caption track to a local file path. Costs 200 quota units.
Inputs: captionId (required), outputPath (required), format, language.
get-playlistB
Read a playlist's items/contents. Costs 1 quota unit per call.
Inputs: playlistId (required), pageToken, maxResults.
get-video-ratingA
Get the authenticated user's rating (like/dislike/none) for up to 50 videos. Costs 1 quota unit per call.
Inputs: videoIds (required).
list-activitiesA
List recent channel activity (uploads, likes, playlist additions, etc.) for a channel, or your own if channelId is omitted. Costs 1 quota unit per call.
Inputs: channelId, pageToken, maxResults.
list-captionsA
List caption tracks for a video. Costs 50 quota units.
Inputs: videoId (required).
list-channelsA
List the authenticated user's own channel(s) with snippet, statistics, and status. Costs 1 quota unit per call.
Inputs: no named parameters.
list-channel-sectionsA
List channel sections (the shelves shown on a channel's homepage) for a channel, or your own if channelId is omitted. Costs 1 quota unit per call.
Inputs: channelId.
list-commentsA
List replies under a top-level comment. Costs 1 quota unit per call.
Inputs: parentId (required), pageToken, maxResults.
list-comment-threadsA
List top-level comment threads for a video or channel. Costs 1 quota unit per call.
Inputs: order, videoId, channelId, pageToken, +1 more.
list-i18n-languagesA
List the application languages supported by YouTube. Costs 1 quota unit per call.
Inputs: no named parameters.
list-i18n-regionsA
List the content regions supported by YouTube. Costs 1 quota unit per call.
Inputs: no named parameters.
list-membersA
List members of your channel's memberships program. Costs 1 quota unit per call. MONETISATION-GATED: 403s unless the channel is an active YouTube Partner Program channel with memberships enabled.
Inputs: mode, pageToken, maxResults, hasAccessToLevel.
list-membership-levelsA
List your channel's membership pricing levels. Costs 1 quota unit per call. MONETISATION-GATED: 403s unless the channel is an active YouTube Partner Program channel with memberships enabled.
Inputs: no named parameters.
list-playlist-imagesA
List cover images for a playlist. Costs 1 quota unit per call.
Inputs: parent (required).
list-playlistsA
List the authenticated user's playlists. Costs 1 quota unit per call.
Inputs: pageToken, maxResults.
list-subscriptionsA
List the authenticated user's channel subscriptions. Costs 1 quota unit per call.
Inputs: pageToken, maxResults.
list-video-abuse-report-reasonsA
List the reason IDs accepted by report-video-abuse. Costs 1 quota unit per call.
Inputs: no named parameters.
list-video-categoriesA
List assignable video categories for a region. Costs 1 quota unit per call.
Inputs: regionCode.
list-videosA
Fetch metadata, status, and statistics for up to 50 videos by ID. Costs 1 quota unit per call.
Inputs: videoIds (required).
rate-videoA
Like, dislike, or clear your rating on a video. Costs 50 quota units.
Inputs: rating (required), videoId (required).
remove-from-playlistA
Permanently remove specific items from a playlist by playlist-item ID. Costs 50 quota units per item. Requires confirm: true.
Inputs: playlistItemIds (required), confirm.
reply-to-commentA
Reply to an existing top-level comment. Costs 50 quota units.
Inputs: text (required), parentId (required).
report-video-abuseA
Report a video to YouTube for abuse/policy violation. Costs 50 quota units. Irreversible outward action — requires confirm: true.
Inputs: videoId (required), reasonId (required), confirm, comments, +2 more.
searchA
Search YouTube for videos, channels, or playlists. Costs 100 quota units per call — use sparingly.
Inputs: query (required), type, maxResults.
set-comment-moderation-statusA
Set the moderation status of one or more comments on your videos — publish, hold for review, or reject (hide from public view; the current replacement for the removed markAsSpam method). Costs 50 quota units. Requires confirm: true.
Inputs: commentIds (required), moderationStatus (required), confirm, banAuthor.
set-thumbnailA
Upload and set a video's custom thumbnail from a local image file. Costs 50 quota units.
Inputs: videoId (required), filePath (required).
set-watermarkA
Upload and set a channel's video watermark from a local image file. Costs 50 quota units.
Inputs: filePath (required), channelId (required), offsetMs, position, +1 more.
subscribeB
Subscribe to a channel. Costs 50 quota units.
Inputs: channelId (required).
unset-watermarkA
Remove a channel's video watermark. Costs 50 quota units. Requires confirm: true.
Inputs: channelId (required), confirm.
unsubscribeA
Unsubscribe from a channel. Costs 50 quota units. Requires confirm: true.
Inputs: subscriptionId (required), confirm.
update-captionA
Update a caption track's draft status, optionally re-uploading its file from a local path. Costs 450 quota units.
Inputs: captionId (required), isDraft, filePath.
update-channelA
Update your channel's branding metadata (title, description, keywords, trailer, language, country). Full-replace on the brandingSettings part — reads the current settings first so omitted fields aren't blanked. Costs 50 quota units.
Inputs: channelId (required), title, country, keywords, +3 more.
update-channel-sectionA
Update an existing channel section. Full-replace on the snippet/contentDetails parts — reads the current section first so omitted fields aren't blanked. Costs 50 quota units.
Inputs: channelSectionId (required), type, style, title, +3 more.
update-commentA
Edit the text of a comment you posted. Costs 50 quota units.
Inputs: text (required), commentId (required).
update-playlistA
Rename, re-describe, or change the privacy of a playlist. Full-replace on the snippet/status parts — reads the current playlist first so omitted fields aren't blanked. Costs 50 quota units.
Inputs: playlistId (required), title, description, privacyStatus.
update-playlist-imageA
Replace a playlist cover image's file. Costs 50 quota units.
Inputs: filePath (required), playlistImageId (required).
update-playlist-itemA
Move a playlist item to a new position (reorder). Costs 50 quota units.
Inputs: videoId (required), position (required), playlistId (required), playlistItemId (required).
update-videoA
Update a video's title, description, category, tags, privacy, and related status flags. Full-replace on the snippet/status parts — reads the current video first so omitted fields aren't blanked. Costs 50 quota units.
Inputs: videoId (required), tags, title, license, +6 more.
upload-captionA
Upload a new caption track from a local file (SRT/VTT/SBV/TTML). Costs 400 quota units.
Inputs: name (required), videoId (required), filePath (required), language (required), +1 more.
upload-playlist-imageA
Upload a cover image for a playlist from a local file. Costs 50 quota units.
Inputs: filePath (required), playlistId (required).
upload-videoA
Upload a video from a local file path via resumable upload. This is the most expensive tool in the server — costs 1600 quota units, 16% of the default daily budget.
Inputs: title (required), filePath (required), tags, categoryId, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 52 tools
Most tools target a distinct resource+action clearly (e.g., list-playlists vs. get-playlist vs. create-playlist). A few pairs like list-videos and list-activities, or list-comments and list-comment-threads, could cause initial confusion but their descriptions differentiate them well. Overall, boundaries are clear despite the large surface.
All tool names follow a consistent lowercase kebab-case verb-noun pattern (e.g., list-channels, create-comment-thread, upload-caption). Even multi-word actions like set-comment-moderation-status adhere to the same scheme. The pattern is predictable and aids discoverability.
52 tools is heavy, exceeding the typical 'too many' threshold. However, the server aims to cover the entire YouTube Data API surface, and most tools map to distinct endpoints or logical operations. Some tools (e.g., list-i18n-languages, list-membership-levels) feel peripheral, but overall the size is defensible.
CRUD/Lifecycle coverage is strong for videos, playlists, comments, captions, and channel sections. Notable gaps include a dedicated get-channel tool for fetching arbitrary channel metadata (only list-channels for own channel), and no way to fetch a playlist's metadata without owning it via list-playlists. Some resources like subscriptions and memberships lack full lifecycle support but list/action tools cover core needs.
Maintenance
Related MCP Connectors
Clean YouTube transcripts for agents: single videos, channels, playlists, plus AI caption cleanup.
Your YouTube library in Claude, ChatGPT and Cursor: transcripts, breakdowns, summaries, search.
Your YouTube library in Claude, ChatGPT and Cursor: transcripts, breakdowns, summaries, search.
YouTube transcripts, search, channels, playlists and bulk transcript jobs for AI agents. 14 tools.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables Claude to interact with YouTube Data API for searching videos, channels, and playlists, and retrieving details and playlists.18 npmMIT
- FlicenseNot gradedqualityDmaintenanceEnables Claude to search YouTube for artists and manage playlists on your YouTube account.1-
- AlicenseNot gradedqualityCmaintenanceEnables Claude to inspect your YouTube playlists for recently added videos and retrieve new items since the last check, powering daily automation that schedules videos into calendar slots.1MIT
- AlicenseNot gradedqualityNot gradedmaintenanceEnables managing a YouTube channel from Claude by listing, searching, editing, and organizing videos and playlists while retrieving channel, video, and thumbnail insights.MIT