Summary
A straightforward bridge to YouTube's Data API v3 that covers the full spectrum from zero-config transcript extraction to OAuth-gated membership data. The transcript tool uses yt-dlp and works immediately with no credentials. Add an API key and you unlock search with filtering by date, duration, and region, plus metadata, comments, trending videos, and caption tracks. OAuth adds private subscriptions and channel membership rosters. The tool list is comprehensive: 20+ operations including handle-based channel lookup, playlist enumeration, activity feeds, and category discovery across regions. If you're building workflows that need to pull YouTube data into Claude without writing API client code, this does the plumbing.
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
Connect AI assistants to YouTube: search, transcripts, metadata, and more.
What can it do?
Once connected, your AI can:
- Extract clean, word-for-word video transcripts. No credentials required.
- Search YouTube by keyword, date range, duration, quality, and region.
- Fetch trending videos for any country and category.
- Retrieve video stats, metadata, comments, captions, and channel details.
- Look up channels by
@handle(e.g.@MrBeast). - Access your own subscriptions, members, and membership tiers via OAuth.
Getting Started
The server supports three access tiers. Pick the one that fits your use case.
Guest Mode (No Setup)
Works out of the box. The get_video_transcript tool uses yt-dlp to extract transcripts without any API credentials.
{
"mcpServers": {
"youtube-mcp": {
"command": "npx",
"args": ["-y", "@mrsknetwork/ytmcp@latest"]
}
}
}
API Key (Recommended)
Unlocks all public data tools. Best for search, metadata, comments, trending videos, and transcripts.
1. Get a Google API Key
- Open the Google Cloud Console.
- Enable YouTube Data API v3 for your project.
- Go to Credentials and create an API Key.
2. Add to your MCP client config
{
"mcpServers": {
"youtube-mcp": {
"command": "npx",
"args": ["-y", "@mrsknetwork/ytmcp@latest", "YOUR_GOOGLE_API_KEY"]
}
}
}
OAuth 2.0
Required for private subscriptions, memberships, and account activity.
1. Create an OAuth 2.0 Client
- Open the Google Cloud Console.
- Enable YouTube Data API v3 for your project.
- Go to Credentials > Create Credentials > OAuth 2.0 Client ID.
- Set Application type to Web application.
- Add this exact Redirect URI:
http://localhost:31415/oauth2callback. - Go to OAuth Consent Screen > Test Users and add your Gmail address.
2. Add to your MCP client config
Credentials are passed securely via environment variables in the MCP config. They are never stored in files.
{
"mcpServers": {
"youtube-mcp": {
"command": "npx",
"args": ["-y", "@mrsknetwork/ytmcp@latest"],
"env": {
"GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
"GOOGLE_CLIENT_SECRET": "your-client-secret"
}
}
}
}
3. First-time login
On your first tool call, the AI will share a login link. Click it, authorize the app in your browser, then tell the AI you are done. Your session is saved. You will not need to log in again unless you revoke access.
4. Signing out
Ask your AI to call revoke_oauth_token to sign out and delete your stored credentials at any time.
Available Tools
| Tool | Auth | Description |
|---|---|---|
get_video_transcript | None | Download a full spoken transcript using yt-dlp. Specify language_code (e.g. en, es) and whether to prefer manual or auto-generated captions. Returns source metadata with the text. |
search_content | API Key | Search YouTube for videos, channels, or playlists. Filter by order, published_after, published_before, video_duration, video_definition, and region_code. Supports pagination. |
get_video_metadata | API Key | Fetch title, description, tags, duration, and stats (views, likes, comments) for one or more videos by ID. |
get_channel_metadata | API Key | Fetch channel profile, subscriber count, video count, and uploads playlist ID. Accepts a channel ID or @handle. |
list_trending_videos | API Key | Fetch the most popular videos on YouTube for a given region_code and optional category_id. Supports pagination. |
list_playlists | API Key | List playlists for a channel, or fetch specific playlists by ID. Returns title, description, and item count. |
list_playlist_items | API Key | List all videos inside a playlist in order. Returns title, position, and video ID for each entry. |
list_video_comments | API Key | Fetch top-level comment threads for a video or channel. Filter by keyword with search_terms. Supports pagination. |
list_comment_replies | API Key | Fetch replies to a specific comment thread by parent_comment_id. Supports pagination. |
list_video_captions | API Key | List available caption tracks for a video, including language code and type (manual or auto-generated). |
list_video_categories | API Key | List YouTube video category names and IDs for a given region. Use the IDs with search_content or list_trending_videos. |
list_channel_activities | API Key | Fetch a channel's recent activity feed, including uploads and playlist additions. |
list_channel_sections | API Key | List the shelf sections displayed on a channel's page, in order. |
list_supported_languages | API Key | List all languages supported by YouTube, with language codes and localized names. |
list_supported_regions | API Key | List all regions supported by YouTube, with region codes and names. |
list_subscriptions | API Key / OAuth | List public subscriptions for a channel by channel_id (API Key), or your own subscriptions with mine=true (OAuth). |
list_channel_members | OAuth | List current paying members of your channel. Requires an active memberships program. |
list_membership_levels | OAuth | List the membership tier names and levels configured for your channel. |
revoke_oauth_token | OAuth | Sign out and permanently delete your stored Google credentials from the server. |
Building from Source
Instructions for running the server locally.
git clone https://github.com/mrsknetwork/ytmcp.git
cd ytmcp
npm install
npm run build
node build/server/index.js "YOUR_API_KEY"
License
Licensed under the MIT License.
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 →Categories
Registryactive
Package@mrsknetwork/ytmcp
TransportSTDIO
UpdatedApr 20, 2026
