Skip to main content
Glama
mcp-youtube
by kud

TypeScript Node.js npm MIT

▶️ 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-ssl scope

  • Quota-aware by design — every tool documents its cost up front, from 1-unit reads to the 1600-unit upload-video

  • Guarded destructive actions — every delete, unsubscribe, moderation action, or other irreversible/outward tool refuses to run without confirm: true

  • Full-replace done safely — YouTube's update methods overwrite an entire resource part; tools like update-video, update-playlist, update-channel, and update-channel-section read the current resource first so an update that only changes one field never silently blanks the rest

  • Safe bulk cleanup — clean-playlist scans 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 removed

  • Local-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 setup handles 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 like

  • Typed 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-youtube

In Claude Code or Claude Desktop you can instead install it as a plugin, which wires up the registration for you:

/plugin install youtube@kud

Either way, run the one-time OAuth setup before first use:

npm run setup

This 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

MCP_YOUTUBE_CLIENT_ID

OAuth client ID

MCP_YOUTUBE_CLIENT_SECRET

OAuth client secret

MCP_YOUTUBE_REFRESH_TOKEN

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-ssl is 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

search, list-playlists, get-playlist

Searching

Playlists

create-playlist, update-playlist, add-to-playlist, update-playlist-item

Creating & Adding

Cleaning

clean-playlist

Cleaning Playlists

Deleting

remove-from-playlist, delete-playlist

Deleting & Pruning

Videos

list-videos, update-video, rate-video, get-video-rating, delete-video, upload-video, report-video-abuse

Videos

Channels & sections

update-channel, list-channels, list-channel-sections, create-channel-section, update-channel-section, delete-channel-section

Channels & Sections

Community

list-subscriptions, subscribe, unsubscribe, list-comment-threads, create-comment-thread, list-comments, reply-to-comment, update-comment, delete-comment, set-comment-moderation-status

Community

Captions & media

list-captions, upload-caption, update-caption, download-caption, delete-caption, set-thumbnail, set-watermark, unset-watermark, list-playlist-images, upload-playlist-image, update-playlist-image, delete-playlist-image

Captions & Media

Reference data

list-activities, list-video-categories, list-i18n-languages, list-i18n-regions, list-video-abuse-report-reasons, list-members, list-membership-levels

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 dev

Script

Purpose

npm run dev

Run the server directly from source (tsx)

npm run build

Compile to dist/

npm test

Run the Vitest suite

npm run typecheck

Type-check without emitting

npm run inspect:dev

Launch the MCP Inspector against source

📚 Full documentation → mcp-youtube/docs

Available Tools

52 tools
add-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.

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

    A3.7/5.0

    Scored across 52 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count3/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers