Summary
OAuth-authenticated YouTube server built for creators who need write access. Goes beyond read-only Data API wrappers by letting you update video metadata, moderate comments, manage playlists, and pull channel analytics. The standout feature is the ComfyUI bridge: generate a thumbnail from a text prompt and push it to YouTube in a single tool call. Runs over streamable HTTP or stdio, handles token refresh automatically, and stays comfortably under the 10k daily quota for most workflows. Useful when you're running a channel from Claude and need more than search and fetch.
Plug Mailtrap into your AI workflow and let it handle the email.
Connect Mailtrap MCP →
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
Make coding agent sessions - Searchable, Shareable, Vendor-neutral & Scored.
Try For Free →
Your agent targets a perfect 10 Code Health score. Deterministic. Every commit.
Try For Free →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
belt cli automatically finds the best tools and skills for your agent. image, video, music, tts...
one prompt install →Tools
Public tool metadata for what this MCP can expose to an agent.
16 tools
YOUTUBE_GET_CHANNEL_ACTIVITIESGets recent activities from a YouTube channel including video uploads, playlist additions, likes, and other channel events.6 params
Gets recent activities from a YouTube channel including video uploads, playlist additions, likes, and other channel events.
Parameters* required
channelIdstringThe YouTube channel ID to retrieve activities for. Channel IDs typically start with 'UC'.
maxResultsintegerMaximum number of activities to return.default: 25
pageTokenstringPagination token from a previous response to get the next page of results.
partstringComma-separated list of activity resource properties to include (e.g., 'snippet', 'contentDetails', 'id').default: snippet,contentDetails
publishedAfterstringReturn activities published after this date-time (RFC 3339 format: YYYY-MM-DDTHH:MM:SSZ).
publishedBeforestringReturn activities published before this date-time (RFC 3339 format: YYYY-MM-DDTHH:MM:SSZ).
YOUTUBE_GET_CHANNEL_ID_BY_HANDLERetrieves the YouTube Channel ID for a specific YouTube channel handle.1 params
Retrieves the YouTube Channel ID for a specific YouTube channel handle.
Parameters* required
channel_handlestringThe YouTube channel handle (e.g., @Google) for which to retrieve the corresponding channel ID. This handle must start with an '@' symbol.
YOUTUBE_GET_CHANNEL_STATISTICSGets detailed statistics for YouTube channels including subscriber counts, view counts, and video counts.2 params
Gets detailed statistics for YouTube channels including subscriber counts, view counts, and video counts.
Parameters* required
idstringComma-separated list of YouTube channel IDs. Channel IDs typically start with 'UC'. This is a required field and must be non-empty
partstringComma-separated list of channel resource properties to include. Use 'statistics' for subscriber count.default: statistics
YOUTUBE_GET_VIDEO_DETAILS_BATCHRetrieves multiple YouTube video resource parts in a single batch call. Use when you need cohort-level metrics for many videos to reduce quota usage and latency.3 params
Retrieves multiple YouTube video resource parts in a single batch call. Use when you need cohort-level metrics for many videos to reduce quota usage and latency.
Parameters* required
hlstringLanguage for localized metadata (snippet.localized); IETF language tag, e.g., 'en'.
idarrayList of YouTube video IDs to retrieve (comma-separated in request).
partsarrayComma-separated list of video resource properties to include. Valid parts can be one or more of: snippet, contentDetails, statistics, status, player, topicDetails, recordingDetails, fileDetails, pr...
YOUTUBE_LIST_CAPTION_TRACKRetrieves a list of caption tracks for a YouTube video, returning an empty list if no captions exist or failing if the video ID is invalid or not found.2 params
Retrieves a list of caption tracks for a YouTube video, returning an empty list if no captions exist or failing if the video ID is invalid or not found.
Parameters* required
partstringSpecifies a comma-separated list of one or more caption resource parts that the API response will include. Valid parts are 'id' and 'snippet'.default: snippet
videoIdstringThe YouTube video ID for which the API should return caption tracks.
YOUTUBE_LIST_CHANNEL_VIDEOSLists videos from a specified YouTube channel, ensuring results are of `type: 'video'`.4 params
Lists videos from a specified YouTube channel, ensuring results are of `type: 'video'`.
Parameters* required
channelIdstringThe unique ID of the YouTube channel for which videos are to be retrieved.
maxResultsintegerThe maximum number of videos to return per page.default: 5
pageTokenstringToken for pagination; use `nextPageToken` from a previous response for the next page, or `prevPageToken` for the previous page.
partstringSpecifies `search` resource properties to include; it must be `snippet` for this action. The `snippet` includes basic video details like ID, title, description, and thumbnails.default: snippet
YOUTUBE_LIST_PLAYLIST_ITEMSTool to list videos in a playlist, with pagination support. Use when walking through a channel's uploads playlist to enumerate all videos.7 params
Tool to list videos in a playlist, with pagination support. Use when walking through a channel's uploads playlist to enumerate all videos.
Parameters* required
fieldsstringSelector specifying which fields to include in a partial response.
maxResultsintegerThe maximum number of items to return per page. Must be between 0 and 50.default: 50
onBehalfOfContentOwnerstringNote: For YouTube content partners. Authorize using a properly scoped account.
pageTokenstringThe token for the page of results to retrieve. Obtained from a previous call's nextPageToken.
partstringComma-separated list of playlistItem resource parts to include in the response. Valid values: 'snippet', 'contentDetails', 'id', 'status'.default: snippet,contentDetails
playlistIdstringThe ID of the playlist for which to retrieve items. Typically a channel's uploads playlist ID.
videoIdstringFilter results to only those containing the specified video ID.
YOUTUBE_LIST_USER_PLAYLISTSRetrieves playlists owned by the authenticated user, implicitly using mine=True.3 params
Retrieves playlists owned by the authenticated user, implicitly using mine=True.
Parameters* required
maxResultsintegerMaximum number of playlists to return.default: 5
pageTokenstringToken for pagination to retrieve a specific page of results.
partstringSpecifies a comma-separated list of one or more playlist resource properties to include in the response. Common values are 'snippet', 'id', and 'contentDetails'.default: snippet
YOUTUBE_LIST_USER_SUBSCRIPTIONSRetrieves the authenticated user's YouTube channel subscriptions, allowing specification of response parts and pagination.3 params
Retrieves the authenticated user's YouTube channel subscriptions, allowing specification of response parts and pagination.
Parameters* required
maxResultsintegerMaximum number of subscription items to return per page.default: 5
pageTokenstringToken for a specific page of results, obtained from a previous response. Omit for the first page.
partstringSpecifies the comma-separated subscription resource parts to include. Valid parts are `id`, `snippet`, `contentDetails`, and `subscriberSnippet`.default: snippet,contentDetails
YOUTUBE_LOAD_CAPTIONSDownloads a specific YouTube caption track, which must be owned by the authenticated user, and returns its content as text. Note: This action requires you to own the video (YouTube Data API v3 restriction). Non-owned videos will return 403 Forbidden errors, including many auto...2 params
Downloads a specific YouTube caption track, which must be owned by the authenticated user, and returns its content as text. Note: This action requires you to own the video (YouTube Data API v3 restriction). Non-owned videos will return 403 Forbidden errors, including many auto...
Parameters* required
idstringUnique YouTube-assigned ID of the caption track to download.
tfmtstringDesired format for the caption track. Supported formats: 'srt' (SubRip), 'sbv' (SubViewer), 'vtt' (WebVTT).default: srt
YOUTUBE_SEARCH_YOU_TUBESearches YouTube for videos, channels, or playlists using a query term, returning the raw API response.5 params
Searches YouTube for videos, channels, or playlists using a query term, returning the raw API response.
Parameters* required
maxResultsintegerMaximum number of items to return per page.default: 5
pageTokenstringPagination token from a previous response's 'nextPageToken' or 'prevPageToken', used to retrieve a specific page of results.
partstringComma-separated list of search resource properties (e.g., 'id', 'snippet') to include in the API response.default: snippet
qstringSearch query term. Supports: - Basic text: 'machine learning' - Exact phrases: '"exact phrase"' - Exclusions: 'python -snake' - Multiple terms: 'AI OR ML' - Channel search: '@channelhandle' or chan...
typestringRestricts search to 'video', 'channel', or 'playlist'; comma-separate for multiple types (e.g., 'video,channel').default: video
YOUTUBE_SUBSCRIBE_CHANNELSubscribes the authenticated user to a specified YouTube channel, identified by its unique `channelId` which must be valid and existing.1 params
Subscribes the authenticated user to a specified YouTube channel, identified by its unique `channelId` which must be valid and existing.
Parameters* required
channelIdstringUnique identifier (ID) of the YouTube channel to subscribe to (typically starts with 'UC').
YOUTUBE_UPDATE_THUMBNAILSets the custom thumbnail for a YouTube video using an image from thumbnailUrl; the authenticated user must have permission to edit the video.2 params
Sets the custom thumbnail for a YouTube video using an image from thumbnailUrl; the authenticated user must have permission to edit the video.
Parameters* required
thumbnailUrlstringPublicly accessible URL of the new thumbnail image. Must be JPG, GIF, or PNG; under 2MB. Recommended: 16:9 aspect ratio, 1280x720 resolution (minimum 640px width).
videoIdstringIdentifier of the YouTube video for which to update the thumbnail.
YOUTUBE_UPDATE_VIDEOUpdates metadata for a YouTube video identified by videoId, which must exist; an empty list for tags removes all existing tags.6 params
Updates metadata for a YouTube video identified by videoId, which must exist; an empty list for tags removes all existing tags.
Parameters* required
categoryIdstringNew YouTube category ID. No change if omitted or `None`.
descriptionstringNew video description. No change if omitted or `None`.
privacyStatusstringNew privacy status ('public', 'private', or 'unlisted'). No change if omitted or `None`.
tagsarrayNew tags, replacing all existing. An empty list removes all. No change if omitted or `None`.
titlestringNew video title. No change if omitted or `None`.
videoIdstringThe video's unique YouTube ID, typically found in its URL.
YOUTUBE_UPLOAD_VIDEOUploads a video from a local file path to a YouTube channel; the video file must be in a YouTube-supported format.6 params
Uploads a video from a local file path to a YouTube channel; the video file must be in a YouTube-supported format.
Parameters* required
categoryIdstringYouTube category ID (e.g., '22' for People & Blogs). See YouTube Data API docs for a full list of category IDs.
descriptionstringDetailed description of the video content, optionally including keywords and context.
privacyStatusstringPrivacy status: 'public', 'private' (uploader/specified users only), or 'unlisted' (link accessible, not publicly listed).
tagsarrayList of keyword tags (strings) for the video, used to improve discoverability.
titlestringThe title for the video.
videoFilePathstringVideo file to upload. Provide a FileUploadable object with valid s3key, mimetype, and name.
YOUTUBE_VIDEO_DETAILSRetrieves specified information parts (e.g., snippet, contentDetails, statistics) for a YouTube video, identified by its ID.2 params
Retrieves specified information parts (e.g., snippet, contentDetails, statistics) for a YouTube video, identified by its ID.
Parameters* required
idstringThe YouTube video ID (typically an 11-character string) for which details are to be retrieved.
partstringComma-separated list of video resource parts that the API response will include. Valid parts: 'snippet' (title, description, thumbnails), 'contentDetails' (duration, definition, dimension), 'statis...default: snippet,contentDetails,statistics
youtube-mcp
OAuth-authenticated YouTube MCP for channel owners. Edit video metadata, reply to and moderate comments, manage playlists, query channel analytics, and generate or set AI thumbnails via a ComfyUI bridge. Goes beyond the read-only Data API v3 wrappers that dominate this space.
The pitch
Most existing YouTube MCPs use an API key against Data API v3. Search videos, fetch public metadata, read-only. This one uses OAuth 2.0 (Authorization Code + PKCE) so it can actually write to your channel: update video titles, descriptions and tags, reply to comments, moderate spam, manage playlists. It also hits the separate YouTube Analytics API for channel stats, and generates a thumbnail via ComfyUI and pushes it to YouTube in a single MCP call.
Claude, use generate_and_set_thumbnail on video abc123:
prompt: "cyberpunk hacker at keyboard, neon blue and pink, high contrast"
ComfyUI renders 1280×720, youtube-mcp fetches the bytes, and POSTs to thumbnails.set. Done.
Install
# npx, no install
npx @miller-joe/youtube-mcp --help
# Docker
docker run -p 9120:9120 \
-e YOUTUBE_CLIENT_ID=... \
-e YOUTUBE_CLIENT_SECRET=... \
-e YOUTUBE_TOKEN_FILE=/token/token.json \
-v $PWD/token:/token \
ghcr.io/miller-joe/youtube-mcp:latest
Setup: Google Cloud one-time (~10 min)
-
Google account plus YouTube channel. Use a personal account, not a workspace one you might lose.
-
Google Cloud project at https://console.cloud.google.com. Call it whatever you want (e.g.
youtube-mcp). -
Enable APIs:
- YouTube Data API v3
- YouTube Analytics API
-
OAuth consent screen: External, App name, support email. In Scopes, add:
youtube.uploadyoutube.force-sslyt-analytics.readonly
-
Stay in Testing mode. Add yourself as a test user (required). As the project owner, your refresh token won't expire.
-
Create OAuth Client ID: Application type = Desktop app. Download the JSON.
-
Run the interactive auth flow:
npx @miller-joe/youtube-mcp --auth --client-secret-file ./client_secret.jsonA browser opens, you log in to the Google account tied to your YouTube channel, and grant the requested scopes. On success, a refresh token is saved to
~/.config/youtube-mcp/token.json. -
Start the server:
npx @miller-joe/youtube-mcp --client-secret-file ./client_secret.jsonOr provide the client credentials via env:
YOUTUBE_CLIENT_SECRET_FILE, orYOUTUBE_CLIENT_ID+YOUTUBE_CLIENT_SECRET.
Connect an MCP client
claude mcp add --transport http youtube http://localhost:9120/mcp
Or point your MCP gateway at the Streamable HTTP endpoint.
Configuration
| CLI flag | Env var | Default | Notes |
|---|---|---|---|
--client-secret-file | YOUTUBE_CLIENT_SECRET_FILE | (none) | Path to Google OAuth JSON |
--client-id | YOUTUBE_CLIENT_ID | (none) | Alternative to the secret file |
--client-secret | YOUTUBE_CLIENT_SECRET | (none) | Alternative to the secret file |
--token-file | YOUTUBE_TOKEN_FILE | ~/.config/youtube-mcp/token.json | Refresh token storage |
--host | MCP_HOST | 0.0.0.0 | Bind host (HTTP mode only) |
--port | MCP_PORT | 9120 | Bind port (HTTP mode only) |
--stdio | MCP_TRANSPORT=stdio | (unset) | Speak MCP over stdio instead of HTTP. Use when launched as a subprocess by a stdio-first MCP client (Claude Desktop, mcp-inspector). |
--comfyui-url | COMFYUI_URL | (unset, bridge disabled) | ComfyUI HTTP URL for bridge tools |
| (no flag) | COMFYUI_DEFAULT_CKPT | sd_xl_base_1.0.safetensors | Default checkpoint for bridge tool |
Transports
The server speaks streamable HTTP by default (great for Claude Code, MetaMCP, raw fetch). Pass --stdio (or set MCP_TRANSPORT=stdio) to switch into stdio mode, which is what stdio-first clients like Claude Desktop and the MCP Inspector expect:
// claude_desktop_config.json
{
"mcpServers": {
"youtube": {
"command": "npx",
"args": ["-y", "@miller-joe/youtube-mcp", "--stdio"],
"env": {
"YOUTUBE_CLIENT_SECRET_FILE": "/path/to/client_secret.json",
"YOUTUBE_TOKEN_FILE": "/path/to/token.json"
}
}
}
}
Stdio mode skips the OAuth-token preflight check — the server boots even without a stored token and surfaces auth errors at tool-call time. Run youtube-mcp --auth --client-secret-file <path> once in HTTP mode to seed the refresh token before pointing Claude Desktop at it.
Tools
Videos
list_my_videos: paginated list of the authenticated channel's uploads.get_video: full detail for one video.update_video_metadata: title, description, tags, category, privacy.delete_video: permanently delete a video. Requiresconfirm_video_titleto match the current title exactly, as a guard against deleting the wrong video.
Captions
list_captions: list caption tracks on a video (language, name, status, draft flag).upload_caption: upload an SRT or WebVTT caption track to a video.delete_caption: delete a caption track.
Shorts
list_my_shorts: find Shorts in recent uploads (filters by duration ≤60s).get_shorts_analytics: YouTube Analytics query restricted to Shorts (creatorContentType==SHORTS).
Playlists
create_playlist: create a playlist (default private).add_to_playlist: add a video to an existing playlist.
Comments
list_comments: top-level comment threads on a video.reply_to_comment: reply to a top-level comment.moderate_comment: hold, approve, or reject a comment.
Analytics
query_channel_analytics: date-ranged metrics with optional dimensions and filters.
Bridge (when COMFYUI_URL is configured)
generate_and_set_thumbnail: generate a thumbnail via ComfyUI and set it on a video in one call.
Quota notes
YouTube Data API free tier = 10,000 units/day. Key operation costs:
videos.list,commentThreads.list: 1 unit each.videos.update,comments.insert,thumbnails.set: 50 units each.videos.insert(upload): 1,600 units, so about 6 uploads per day on the free tier.
Most creator-ops workflows stay well under the free cap.
Architecture
┌────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ MCP client │────▶│ youtube-mcp │────▶│ YouTube APIs │
│ (Claude etc.) │◀────│ (this server) │◀────│ (Data/Analytics)│
└────────────────┘ └────────┬─────────┘ └─────────────────┘
│
│ (bridge tools only)
▼
┌──────────────────┐
│ ComfyUI │
│ (txt2img) │
└──────────────────┘
OAuth refresh tokens are cached locally and refreshed just-in-time before expiry. The bridge tool downloads image bytes from ComfyUI internally, so ComfyUI does not need to be publicly reachable.
Development
git clone https://github.com/miller-joe/youtube-mcp
cd youtube-mcp
npm install
npm run dev
npm run build
npm test
Requires Node 20+.
Roadmap
Shipped:
- Videos: list, get, update metadata, delete with title-match confirm guard.
- Captions: upload, list, delete.
- Shorts:
list_my_shorts(duration filter) andget_shorts_analytics(creatorContentType==SHORTS). - Playlists: create, add-to.
- Comments: list, reply, moderate.
- Analytics: channel analytics query.
- ComfyUI thumbnail bridge:
generate_and_set_thumbnail.
Planned:
- Video upload (
video_upload) with resumable-upload support. - Reporting API for bulk historical data exports.
License
MIT © Joe Miller
Support
If this saves you time, consider supporting development:
Featured
Plug Mailtrap into your AI workflow and let it handle the email.
Connect Mailtrap MCP →Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →Make coding agent sessions - Searchable, Shareable, Vendor-neutral & Scored.
Try For Free →Your agent targets a perfect 10 Code Health score. Deterministic. Every commit.
Try For Free →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →belt cli automatically finds the best tools and skills for your agent. image, video, music, tts...
one prompt install →Configuration
YOUTUBE_CLIENT_ID*Google OAuth 2.0 Client ID (from Google Cloud Console, Desktop app type). See README for setup.
YOUTUBE_CLIENT_SECRET*secretGoogle OAuth 2.0 Client Secret. Pair with YOUTUBE_CLIENT_ID.
YOUTUBE_CLIENT_SECRET_FILEAlternative to CLIENT_ID/CLIENT_SECRET: path to the JSON credentials file downloaded from Google Cloud.
YOUTUBE_TOKEN_FILERefresh token storage path. Default: ~/.config/youtube-mcp/token.json
COMFYUI_URLComfyUI HTTP URL for the generate_and_set_thumbnail bridge tool. When unset, that tool is disabled.
COMFYUI_DEFAULT_CKPTDefault ComfyUI checkpoint filename for bridge tool (default: sd_xl_base_1.0.safetensors)
Categories
Registryactive
Package@miller-joe/youtube-mcp
TransportHTTP
AuthRequired
UpdatedApr 20, 2026
