YouTube MCP Server
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| YOUTUBE_API_KEY | No | API key for public read-only calls. Also used for reading comments with a strictly read-only OAuth login. | |
| YOUTUBE_CHANNEL_ID | No | Default channel ID or @handle to use when only an API key is set. | |
| YOUTUBE_TOKEN_FILE | No | Where to store the OAuth token. | token.json |
| YOUTUBE_REPORT_WEBHOOK | No | Slack-compatible incoming webhook URL used by report and alerts. This value is a secret. | |
| YOUTUBE_CLIENT_SECRET_FILE | No | Path to the OAuth client JSON file. | client_secret.json |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Read-only access to YouTube: channels, videos, playlists, search, and (with OAuth) YouTube Analytics for the authenticated channel. Nothing here can upload, edit, or delete.
Start with auth_status if unsure what works: an API key supports public data
only; analytics tools (get_channel_analytics, get_video_analytics,
get_top_videos, get_revenue, get_audience_insights, get_search_terms) need OAuth, set up by the user running
python cli.py auth.
Comments: list_comments reads public comments on one video or on a whole channel (any channel, API key is enough).
Channels are given as a channel ID (UC...) or a handle (@name). Leave the channel empty to mean the authenticated user's own channel (OAuth) or the configured default (API key).
Dates are YYYY-MM-DD and inclusive. Analytics lags by 2-3 days.
QUOTA: the project has a daily quota (10,000 units by default). Most calls cost 1 unit; search_videos costs ~100. Prefer list_channel_videos over searching a channel. Errors begin with a code such as QUOTA_EXCEEDED, OAUTH_REQUIRED, AUTH_ERROR, NOT_FOUND, or INVALID_REQUEST.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| auth_statusA | Which credentials are available (API key, OAuth token, both, or neither) and which tools work with them. Includes next steps for enabling anything unsupported. Never opens a browser. |
| get_channel_infoC | Channel name, description, subscriber count, video count, total views, and uploads playlist ID. |
| list_channel_videosB | A channel's uploaded videos, newest first, with basic stats. Paginated via next_page_token. |
| get_video_detailsA | Full details for one or more videos: title, description, views, likes, comment count, duration, publish date, tags, thumbnails. IDs that are deleted, private, or wrong are listed under not_found. |
| search_videosA | Keyword search over public videos with date, order, region and channel filters. Costs ~100 quota units per call. |
| compare_channelsA | Benchmark channels side by side: subscribers, total views, and over their recent uploads the median views, engagement rate, upload frequency, share of Shorts and top video. Public data; about 3 quota units per channel. Good for competitor tracking. |
| get_trending_videosA | YouTube's most-popular videos in a country right now, optionally in one category, with stats. 1 quota unit. |
| list_commentsA | Public comment threads on a video or on all of a channel's videos: text, author, likes, date, reply count, first replies. owner_replied tells whether the channel answered in the included replies, which helps find unanswered questions. Paginated via next_page_token; 1 quota unit per page. Held-for-review comments are not visible. |
| get_comment_repliesA | All replies to one comment thread, for threads with more replies than list_comments includes. |
| get_channel_analyticsA | Views, watch time (estimatedMinutesWatched), average view duration, subscribers gained/lost, likes, comments and shares for your channel. Requires OAuth; returns an OAUTH_REQUIRED error with setup steps otherwise. |
| get_video_analyticsA | Analytics for one video: summary metrics, traffic sources, audience retention curve, and viewer demographics. Requires OAuth; returns an OAUTH_REQUIRED error with setup steps otherwise. |
| get_top_videosA | Your channel's top N videos by a metric over a date range, with titles and key metrics. Requires OAuth; returns an OAUTH_REQUIRED error with setup steps otherwise. |
| get_revenueA | Estimated revenue, ad revenue, gross revenue and CPM for your channel. Returns available=false with the reason if the channel is not monetized or the token lacks the monetary scope. Requires OAuth. |
| get_audience_insightsA | Who watches and how: countries, cities, devices, playback locations (incl. embeds on websites), traffic sources, subscribers vs not, Shorts vs long-form, sharing, cards. Each breakdown lists rows sorted by views with their share of the total. Requires OAuth. |
| get_search_termsA | The YouTube search terms viewers typed before watching your videos, with views and watch time per term. Useful for titles, descriptions and tags. Requires OAuth. |
| get_channel_reportA | A ready-made performance report: totals and % change vs the previous period, net subscribers, top videos, audience highlights and top YouTube searches. Includes the same report rendered as Markdown under |
| detect_anomaliesA | Find recent days with unusual views (spikes and drops against the median of the days before) and days that lost subscribers. Data ends ~2 days ago because analytics lag. Requires OAuth. |
| list_playlistsB | A channel's playlists with title, description and item count. Paginated via next_page_token. |
| get_playlist_itemsB | Videos in a playlist, in playlist order, plus the playlist's own details on the first page. Paginated. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 19 tools
Most tools target a clear resource+action pair (public metadata retrieval vs. OAuth analytics vs. comments vs. playlists). The main soft spot is that get_channel_report bundles totals, top videos, audience highlights and search terms, which overlaps with get_channel_analytics, get_top_videos, get_audience_insights and get_search_terms, so an agent may hesitate between the bundle and the individual breakdowns. Descriptions do explicitly clarify the distinction, so confusion is limited rather than systemic.
Strong, predictable verb_noun pattern throughout: get_/list_/search_/compare_/detect_ plus a domain noun (get_video_details, list_channel_videos, get_audience_insights). The only deviation is auth_status, which is a bare noun rather than a verb phrase—minor and still readable.
19 tools is slightly above the ideal band but each maps to a recognizable YouTube resource or report type, and the public-data vs. OAuth split is coherent. The composite get_channel_report is the one arguably redundant entry given the granular tools it overlaps with, which keeps this from a 5.
Read and analytics coverage is genuinely thorough: channel/video metadata, playlists, comments and replies, trending, search, revenue, audience, search terms, anomalies and a shareable report. The gaps are on the write side—no uploading or updating videos, no posting comments/replies, no playlist creation—and no captions/transcript access, so the surface is read-only but that limitation is not stated up front.