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.
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →
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
partstringComma-separated list of activity resource properties to include (e.g., 'snippet', 'contentDetails', 'id').default: snippet,contentDetails
channelIdstringThe YouTube channel ID to retrieve activities for. Channel IDs typically start with 'UC'.
pageTokenstringPagination token from a previous response to get the next page of results.
maxResultsintegerMaximum number of activities to return.default: 25
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, processingDetails, suggestions, liveStreamingDetails, localizations, paidProductPlacementDetails, id.
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
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
channelIdstringThe unique ID of the YouTube channel for which videos are to be retrieved.
pageTokenstringToken for pagination; use `nextPageToken` from a previous response for the next page, or `prevPageToken` for the previous page.
maxResultsintegerThe maximum number of videos to return per page.default: 5
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
partstringComma-separated list of playlistItem resource parts to include in the response. Valid values: 'snippet', 'contentDetails', 'id', 'status'.default: snippet,contentDetails
fieldsstringSelector specifying which fields to include in a partial response.
videoIdstringFilter results to only those containing the specified video ID.
pageTokenstringThe token for the page of results to retrieve. Obtained from a previous call's nextPageToken.
maxResultsintegerThe maximum number of items to return per page. Must be between 0 and 50.default: 50
playlistIdstringThe ID of the playlist for which to retrieve items. Typically a channel's uploads playlist ID.
onBehalfOfContentOwnerstringNote: For YouTube content partners. Authorize using a properly scoped account.
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
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
pageTokenstringToken for pagination to retrieve a specific page of results.
maxResultsintegerMaximum number of playlists to return.default: 5
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
partstringSpecifies the comma-separated subscription resource parts to include. Valid parts are `id`, `snippet`, `contentDetails`, and `subscriberSnippet`.default: snippet,contentDetails
pageTokenstringToken for a specific page of results, obtained from a previous response. Omit for the first page.
maxResultsintegerMaximum number of subscription items to return per page.default: 5
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
qstringSearch query term. Supports: - Basic text: 'machine learning' - Exact phrases: '"exact phrase"' - Exclusions: 'python -snake' - Multiple terms: 'AI OR ML' - Channel search: '@channelhandle' or channel name
partstringComma-separated list of search resource properties (e.g., 'id', 'snippet') to include in the API response.default: snippet
typestringRestricts search to 'video', 'channel', or 'playlist'; comma-separate for multiple types (e.g., 'video,channel').default: video
pageTokenstringPagination token from a previous response's 'nextPageToken' or 'prevPageToken', used to retrieve a specific page of results.
maxResultsintegerMaximum number of items to return per page.default: 5
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
videoIdstringIdentifier of the YouTube video for which to update the thumbnail.
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).
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
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.
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`.
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
tagsarrayList of keyword tags (strings) for the video, used to improve discoverability.
titlestringThe title for the video.
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).
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), 'statistics' (view count, like count, comment count), 'status' (upload status, privacy status), 'player' (embed HTML), 'topicDetails' (associated topics), 'recordingDetails' (recording location and date), 'liveStreamingDetails' (live broadcast details), and 'localizations' (localized metadata).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
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →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
