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.
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
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 or .env file
Pass GOOGLE_API_KEY via env in your MCP client config, or place GOOGLE_API_KEY=YOUR_KEY inside a .env file in the project directory.
{
"mcpServers": {
"youtube-mcp": {
"command": "npx",
"args": ["-y", "@mrsknetwork/ytmcp@latest"],
"env": {
"GOOGLE_API_KEY": "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
cp .env.example .env # Set GOOGLE_API_KEY inside .env
node build/server/index.js
License
Licensed under the MIT License.
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 →Categories
Registryactive
Package@mrsknetwork/ytmcp
TransportSTDIO
UpdatedApr 20, 2026
