YouTube MCP Server
This server gives AI assistants comprehensive control over YouTube channels via MCP, covering data, analytics, publishing, and more.
Authentication & status – init OAuth flow, check auth state and quota usage
Channel & video info – get channel details, list videos, fetch video metadata/statistics
Search & SEO – search videos/channels/playlists, autocomplete suggestions, trending videos, category lookup
Transcripts & captions – fetch transcripts for any public video (scraper fallback) or official captions for owned videos
YouTube Analytics – channel overview, top videos/shorts, video detail, traffic sources, demographics, geography, daily trends, day-of-week performance, content type breakdown, revenue, and audience retention
Video publishing – upload, update metadata, set thumbnails, delete videos
Playlist management – list, create, add to, and remove from playlists
Comments – list, post top-level comments, and reply to comments
Bulk reporting – list report types, create/manage reporting jobs, list generated reports, download report CSVs
Provides tools for interacting with the YouTube Data API, Analytics API, and Reporting API, enabling video management, analytics, transcripts, comments, playlists, uploads, and SEO insights.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@YouTube MCP Server show me my channel's analytics for last week"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Fork note (felipefontoura): patched the transcript scraper for
youtube-transcript-api>=1.0.0. Upstream 0.1.0 declared>=1.0.0but still called the removed 0.6.xYouTubeTranscriptApi.list_transcripts()/ dict-style snippets, soyoutube_get_transcriptalways errored. Now usesYouTubeTranscriptApi().list()+.fetch().to_raw_data(). Seesrc/youtube_mcp/tools/transcripts.py.
YouTube MCP Server
A comprehensive Model Context Protocol server for the YouTube Data API v3, Analytics API, and Reporting API. Gives AI assistants full access to your YouTube channel — analytics, video management, comments, and more.
40 tools covering:
Channel & video data
YouTube Analytics (performance, audience, retention, revenue)
Video publishing & playlist management
Transcript extraction
YouTube SEO (search suggestions, trending)
Comments
Bulk reporting
Why This Server?
Existing YouTube MCP servers focus narrowly on transcript scraping or basic search. This server covers three YouTube APIs and is the only open-source MCP server that provides:
YouTube Analytics API — channel performance, top videos/Shorts, audience retention curves, traffic sources, demographics, revenue, day-of-week analysis
YouTube Reporting API — schedule and download bulk CSV reports
Full Data API coverage — not just read, but also upload videos, manage playlists, post comments, set thumbnails
YouTube SEO tools — autocomplete suggestions, trending videos, category discovery
Dual transcript strategy — official captions API for your own videos,
youtube-transcript-apifallback for any public videoQuota tracking — client-side tracking with hard-fail protection so you don't silently exhaust your daily quota
Feature | This server | Others |
Analytics API (watch time, retention, CTR) | Yes | No |
Reporting API (bulk CSV exports) | Yes | No |
Video upload & management | Yes | Rare |
Playlist management | Yes | Rare |
Comments (read + write) | Yes | No |
SEO / trending / suggestions | Yes | No |
Transcript extraction | Yes | Yes |
Quota tracking | Yes | No |
Total tools | 40 | 1-5 |
Related MCP server: mcp-server-youtube
Prerequisites
Python 3.11+
A Google Cloud project with YouTube APIs enabled
OAuth 2.0 credentials
Google Cloud Setup
1. Create a Google Cloud Project
Go to Google Cloud Console
Create a new project (or use an existing one)
2. Enable APIs
Enable all three APIs in APIs & Services > Library:
YouTube Data API v3
YouTube Analytics API
YouTube Reporting API
3. Configure OAuth Consent Screen
Go to APIs & Services > OAuth consent screen
Set User Type to External
Fill in the app name and required fields
Add the Google account that owns your YouTube channel as a test user
Important: You must sign in with the Google account that owns the YouTube channel, not a manager. Only the owner account can access Analytics data.
4. Create OAuth Credentials
Go to APIs & Services > Credentials
Click Create Credentials > OAuth client ID
Application type: Desktop app
Download the JSON file
Save it as
~/.youtube-mcp/client_secret.json
Alternatively, set the YOUTUBE_MCP_CLIENT_SECRET environment variable to the path of your credentials file.
Required OAuth scopes
The consent flow requests all scopes the server uses. One of them is easy to miss and cannot be substituted:
Scope | Needed by |
| comments and captions — mandatory, no alternative |
| reading videos, channels, playlists |
| uploading videos |
| Analytics queries |
| revenue figures |
commentThreads.list, comments.list, commentThreads.insert,
comments.insert, captions.list and captions.download accept only
youtube.force-ssl (captions also accept youtubepartner, which is a different
product). A token authorised without it still works for everything else and
fails those calls with:
HTTP 403 "Request had insufficient authentication scopes"If you hit that, the token was granted without the scope. Re-run the consent
flow and approve the full permission list — youtube_auth_status now reports
missing_scopes so this is visible up front rather than only at call time.
Adding
youtube.force-sslis a sensitive scope. If your OAuth app is in "Testing" mode, the channel-owning account must be listed as a test user (step 3) or consent will be refused.
Provisioning a token without filesystem access
The token is self-contained (it carries its own client_id, client_secret and
refresh_token), so it can be supplied inline instead of as a file — useful when
the server runs in a container whose config_dir you cannot write to:
export YOUTUBE_MCP_TOKEN_JSON='{"token":"...","refresh_token":"...","client_id":"...","client_secret":"...","scopes":["..."]}'This takes priority over token.json. Note it puts the refresh token wherever
your environment variables are stored, so prefer the file when you have access.
Installation
pip install youtube-studio-mcpOr with uv:
uv pip install youtube-studio-mcpMCP Client Configuration
Claude Desktop
Add to your claude_desktop_config.json:
{
"mcpServers": {
"youtube": {
"command": "youtube-studio-mcp"
}
}
}Claude Code
Add to your MCP settings:
{
"mcpServers": {
"youtube": {
"command": "youtube-studio-mcp"
}
}
}With environment variables
{
"mcpServers": {
"youtube": {
"command": "youtube-studio-mcp",
"env": {
"YOUTUBE_MCP_CLIENT_SECRET": "/path/to/client_secret.json",
"YOUTUBE_API_KEY": "your-api-key-for-public-data"
}
}
}
}First Run
On first use, the server will open a browser window for Google OAuth consent. Sign in with the account that owns your YouTube channel and grant the requested permissions. The token is saved to ~/.youtube-mcp/token.json and auto-refreshes.
Tools Reference
Auth & Setup (2 tools)
Tool | Description |
| Initiate OAuth 2.0 flow |
| Check auth state and quota usage |
Channel & Video (3 tools)
Tool | Description |
| Get channel details by ID, handle, or |
| List videos from a channel or playlist |
| Get detailed video metadata and stats |
Search & SEO (4 tools)
Tool | Description |
| Search YouTube (100 quota units per call) |
| Get autocomplete suggestions (no quota cost) |
| Get trending videos by region/category |
| List video categories for a region |
Transcripts (2 tools)
Tool | Description |
| Get video transcript (official API or scraping fallback) |
| List caption tracks for own videos |
Analytics — Performance (4 tools)
Tool | Description |
| Channel summary (views, watch time, subs, likes) |
| Top videos by views (excludes Shorts) |
| Top Shorts by views |
| Daily metrics for a specific video |
Analytics — Audience (3 tools)
Tool | Description |
| Traffic source breakdown |
| Age and gender breakdown |
| Views by country |
Analytics — Schedule & Reach (3 tools)
Tool | Description |
| Daily performance over time |
| Average performance by weekday |
| Shorts vs long-form vs live comparison |
Analytics — Revenue & Retention (3 tools)
Tool | Description |
| Revenue breakdown (requires YouTube Partner Program) |
| Per-video revenue |
| Audience retention curve for a video |
Publishing (4 tools)
Tool | Description |
| Upload a video (1,600 quota units) |
| Update video metadata |
| Upload custom thumbnail |
| Delete a video |
Playlists (4 tools)
Tool | Description |
| List playlists for a channel |
| Create a new playlist |
| Add a video to a playlist |
| Remove a video from a playlist |
Comments (3 tools)
Tool | Description |
| List comments on a video |
| Post a top-level comment |
| Reply to a comment |
Bulk Reporting (5 tools)
Tool | Description |
| List available report types |
| Schedule a daily report job |
| List active reporting jobs |
| List generated reports for a job |
| Download a report CSV |
Quota Management
The YouTube Data API v3 has a default daily quota of 10,000 units. This server tracks quota usage client-side and hard-fails when the quota is exhausted.
Key costs:
Most read operations: 1 unit
Search: 100 units
Write operations: 50 units
Video upload: 1,600 units
Use youtube_auth_status to check current quota usage.
Environment Variables
Variable | Description |
| Path to |
| Config directory (default: |
| API key for public-only operations |
Development
git clone https://github.com/pauling-ai/youtube-studio-mcp.git
cd youtube-studio-mcp
uv venv && uv pip install -e ".[dev]"
.venv/bin/python -m pytest tests/ -vLicense
MIT
Available Tools
40 toolsyoutube_add_to_playlistC
Add a video to a playlist.
Args: playlist_id: Playlist ID to add the video to video_id: Video ID to add position: Position in the playlist (0-based). Defaults to end.
Inputs: video_id (required), playlist_id (required), position.
youtube_analytics_content_type_breakdownB
Compare performance of Shorts vs long-form videos vs live streams.
Args: start_date: Start date (YYYY-MM-DD). Defaults to 28 days ago. end_date: End date (YYYY-MM-DD). Defaults to today.
Inputs: end_date, start_date.
youtube_analytics_dailyA
Get daily performance metrics over time.
Useful for spotting trends and finding optimal posting days. Returns one row per day with views, watch time, subs, likes, shares.
Args: start_date: Start date (YYYY-MM-DD). Defaults to 28 days ago. end_date: End date (YYYY-MM-DD). Defaults to today.
Inputs: end_date, start_date.
youtube_analytics_day_of_weekB
Get aggregated performance by day of week.
Fetches daily data and aggregates by weekday to show which days perform best. Useful for scheduling uploads.
Args: start_date: Start date (YYYY-MM-DD). Defaults to 90 days ago. end_date: End date (YYYY-MM-DD). Defaults to today.
Inputs: end_date, start_date.
youtube_analytics_demographicsA
Get audience demographics — age group and gender breakdown.
Args: start_date: Start date (YYYY-MM-DD). Defaults to 28 days ago. end_date: End date (YYYY-MM-DD). Defaults to today.
Inputs: end_date, start_date.
youtube_analytics_geographyC
Get views by country.
Args: start_date: Start date (YYYY-MM-DD). Defaults to 28 days ago. end_date: End date (YYYY-MM-DD). Defaults to today. max_results: Number of countries to return.
Inputs: end_date, start_date, max_results.
youtube_analytics_overviewB
Get channel-level analytics summary.
Returns views, watch time, subscribers gained/lost, likes, comments, and shares for the date range.
Args: start_date: Start date (YYYY-MM-DD). Defaults to 28 days ago. end_date: End date (YYYY-MM-DD). Defaults to today.
Inputs: end_date, start_date.
youtube_analytics_retentionB
Get audience retention curve for a specific video.
Returns 100 data points showing what percentage of viewers are still watching at each point in the video. Also includes relative retention compared to similar-length videos on YouTube.
Args: video_id: YouTube video ID start_date: Start date (YYYY-MM-DD). Defaults to 28 days ago. end_date: End date (YYYY-MM-DD). Defaults to today.
Inputs: video_id (required), end_date, start_date.
youtube_analytics_revenueB
Get revenue breakdown.
Requires the channel to be in the YouTube Partner Program (monetized). Returns estimated revenue, ad revenue, and YouTube Premium revenue.
Args: start_date: Start date (YYYY-MM-DD). Defaults to 28 days ago. end_date: End date (YYYY-MM-DD). Defaults to today.
Inputs: end_date, start_date.
youtube_analytics_revenue_by_videoB
Get revenue per video, sorted by highest revenue.
Requires the channel to be in the YouTube Partner Program.
Args: start_date: Start date (YYYY-MM-DD). Defaults to 28 days ago. end_date: End date (YYYY-MM-DD). Defaults to today. max_results: Number of videos to return (max 200).
Inputs: end_date, start_date, max_results.
youtube_analytics_top_shortsB
Get top-performing Shorts by views.
Returns per-Short metrics sorted by view count.
Args: start_date: Start date (YYYY-MM-DD). Defaults to 28 days ago. end_date: End date (YYYY-MM-DD). Defaults to today. max_results: Number of Shorts to return (max 200).
Inputs: end_date, start_date, max_results.
youtube_analytics_top_videosB
Get top-performing videos by views.
Returns per-video metrics sorted by view count, excluding Shorts.
Args: start_date: Start date (YYYY-MM-DD). Defaults to 28 days ago. end_date: End date (YYYY-MM-DD). Defaults to today. max_results: Number of videos to return (max 200).
Inputs: end_date, start_date, max_results.
youtube_analytics_traffic_sourcesB
Get traffic source breakdown — how viewers find your content.
Shows views from search, suggested, browse, external, etc.
Args: start_date: Start date (YYYY-MM-DD). Defaults to 28 days ago. end_date: End date (YYYY-MM-DD). Defaults to today. video_id: Optional video ID to filter to a specific video.
Inputs: end_date, video_id, start_date.
youtube_analytics_video_detailB
Get detailed analytics for a specific video over time.
Returns daily metrics for the specified video.
Args: video_id: YouTube video ID start_date: Start date (YYYY-MM-DD). Defaults to 28 days ago. end_date: End date (YYYY-MM-DD). Defaults to today.
Inputs: video_id (required), end_date, start_date.
youtube_authA
Initiate OAuth 2.0 authentication flow.
Opens a browser window for Google OAuth consent. Required before using any tools that access private channel data or analytics.
Inputs: no named parameters.
youtube_auth_statusC
Check current authentication status and quota usage.
Inputs: no named parameters.
youtube_create_playlistC
Create a new playlist.
Args: title: Playlist title description: Playlist description privacy_status: "private", "public", or "unlisted"
Inputs: title (required), description, privacy_status.
youtube_delete_videoA
Delete a video. This action is irreversible.
Args: video_id: YouTube video ID to delete
Inputs: video_id (required).
youtube_get_categoriesA
List available YouTube video categories for a region.
Useful for filtering trending videos or setting video category on upload. Costs 1 quota unit.
Args: region_code: ISO 3166-1 alpha-2 country code (e.g., "US")
Inputs: region_code.
youtube_get_channelA
Get channel details by channel ID, handle (@username), or the authenticated user's channel.
Args: channel_id: YouTube channel ID (e.g., "UCxxxxxxx") handle: Channel handle (e.g., "@mkbhd") mine: If True, get the authenticated user's own channel
Inputs: mine, handle, channel_id.
youtube_get_transcriptA
Get the transcript/captions for a video.
By default uses youtube-transcript-api (works for any public video, no quota cost). Set use_official_api=True to use the official Data API (only for your own videos, costs quota units).
Args: video_id: YouTube video ID language: Preferred language code (e.g., "en", "es", "ja") use_official_api: If True, use official API (own videos only)
Inputs: video_id (required), language, use_official_api.
youtube_get_videoB
Get detailed metadata and statistics for a specific video.
Args: video_id: YouTube video ID (e.g., "dQw4w9WgXcQ")
Inputs: video_id (required).
youtube_list_captionsB
List available caption tracks for a video you own.
Requires OAuth. Only works for videos on the authenticated user's channel.
Args: video_id: YouTube video ID
Inputs: video_id (required).
youtube_list_commentsB
List top-level comments on a video.
Args: video_id: YouTube video ID max_results: Number of comment threads to return (max 100) order: Sort order: "relevance" or "time"
Inputs: video_id (required), order, max_results.
youtube_list_playlistsB
List playlists for a channel.
Args: channel_id: Channel ID to list playlists from mine: If True, list the authenticated user's playlists max_results: Number of playlists to return (max 50)
Inputs: mine, channel_id, max_results.
youtube_list_videosA
List videos from a channel or playlist.
For a channel, uses the channel's uploads playlist. Returns video summaries with stats, sorted by most recent.
Args: channel_id: Channel ID to list videos from playlist_id: Playlist ID to list videos from (overrides channel_id) mine: If True, list the authenticated user's videos max_results: Number of videos to return (max 50)
Inputs: mine, channel_id, max_results, playlist_id.
youtube_post_commentC
Post a new top-level comment on a video.
Args: video_id: YouTube video ID to comment on text: Comment text
Inputs: text (required), video_id (required).
youtube_remove_from_playlistA
Remove a video from a playlist.
Use youtube_list_playlists or the Data API to find the playlist_item_id.
Args: playlist_item_id: The playlist item ID (not the video ID)
Inputs: playlist_item_id (required).
youtube_reply_to_commentC
Reply to an existing comment.
Args: parent_id: The comment ID to reply to (from youtube_list_comments) text: Reply text
Inputs: text (required), parent_id (required).
youtube_reporting_create_jobB
Schedule a reporting job. Reports will be generated daily.
Once created, YouTube will start generating daily CSV reports for this report type. It may take 24-48 hours for the first report to appear.
Args: report_type_id: Report type ID (from youtube_reporting_list_types) name: Optional human-readable name for the job
Inputs: report_type_id (required), name.
youtube_reporting_downloadA
Download a report CSV.
Returns the CSV content as text. For large reports, the content may be truncated.
Args: download_url: Download URL from youtube_reporting_list_reports
Inputs: download_url (required).
youtube_reporting_list_jobsC
List all active reporting jobs.
Inputs: no named parameters.
youtube_reporting_list_reportsB
List available reports for a job.
Reports are generated daily and available for 60 days.
Args: job_id: Job ID (from youtube_reporting_create_job or youtube_reporting_list_jobs)
Inputs: job_id (required).
youtube_reporting_list_typesA
List available report types that can be scheduled.
Common report types:
channel_basic_a3: User activity (views, watch time, subs)
channel_demographics_a1: Age/gender breakdown
channel_traffic_source_a3: Traffic sources
channel_device_os_a3: Device and OS breakdown
channel_combined_a3: Combined multi-dimension report
Inputs: no named parameters.
youtube_searchA
Search YouTube for videos, channels, or playlists.
Costs 100 quota units per call — use sparingly.
Args: query: Search query string search_type: Type of results: "video", "channel", or "playlist" channel_id: Limit search to a specific channel max_results: Number of results (max 50) order: Sort order: "relevance", "date", "viewCount", "rating" published_after: ISO 8601 datetime (e.g., "2025-01-01T00:00:00Z") published_before: ISO 8601 datetime region_code: ISO 3166-1 alpha-2 country code (e.g., "US")
Inputs: query (required), order, channel_id, max_results, +4 more.
youtube_search_suggestionsB
Get YouTube autocomplete/search suggestions for a query.
Useful for SEO keyword research — shows what people are searching for. No quota cost (uses YouTube's public suggest endpoint).
Args: query: Partial search query to get suggestions for language: Language code (e.g., "en", "es")
Inputs: query (required), language.
youtube_set_thumbnailA
Upload a custom thumbnail for a video.
Args: video_id: YouTube video ID file_path: Absolute path to the thumbnail image (JPEG, PNG, GIF, BMP; max 2MB)
Inputs: video_id (required), file_path (required).
youtube_trendingA
Get currently trending videos on YouTube.
Costs 1 quota unit.
Args: region_code: ISO 3166-1 alpha-2 country code (e.g., "US", "GB", "IN") category_id: Filter by category ID (e.g., "28" for Science & Technology) max_results: Number of videos to return (max 50)
Inputs: category_id, max_results, region_code.
youtube_update_videoB
Update metadata for an existing video.
Only provided fields are updated; others remain unchanged.
Args: video_id: YouTube video ID title: New title (max 100 characters) description: New description (max 5,000 characters) tags: New tags (replaces existing tags) category_id: New category ID privacy_status: "private", "public", or "unlisted"
Inputs: video_id (required), tags, title, category_id, +2 more.
youtube_upload_videoA
Upload a video to YouTube.
Costs 1,600 quota units. Video is uploaded as private by default.
Args: file_path: Absolute path to the video file title: Video title (max 100 characters) description: Video description (max 5,000 characters) tags: List of tags category_id: YouTube category ID (default "22" = People & Blogs) privacy_status: "private", "public", or "unlisted" publish_at: ISO 8601 datetime to schedule publishing (requires privacy_status="private")
Inputs: title (required), file_path (required), tags, publish_at, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 40 tools
Most tools are clearly distinct by domain (analytics, reporting, playlists, comments, video CRUD), with informative descriptions. The only mild confusion is between youtube_list_videos vs youtube_get_video (list vs detail is standard) and the multiple analytics_* tools are well-differentiated by their specific focus (traffic, geography, demographics, etc.). No two tools appear to do the same thing.
The server consistently uses a youtube_ prefix followed by a clear verb_noun pattern (list_videos, get_video, create_playlist, upload_video, delete_video). Minor deviations: youtube_search_suggestions vs youtube_get_categories, and the reporting tools use a subnamespace (youtube_reporting_list_*) which is structured and predictable. Youtube_analytics_* tools follow a consistent subpattern, though the flat prefix gets long.
At 40 tools, this is on the heavy side and exceeds the typical well-scoped range (3-15). However, YouTube's API surface is genuinely broad, spanning auth, search, channel/video/playlist CRUD, comments, captions, analytics (10+ dedicated tools), reporting, and uploads. The size is defensible for the scope, though it sits above the comfortable threshold.
The tool surface is remarkably comprehensive. It covers video lifecycle (upload, get, list, update, delete, thumbnail), playlist lifecycle, comments (list, post, reply), search, captions/transcripts, trending, channel info, full analytics coverage (overview, top videos, top shorts, demographics, geography, traffic, retention, revenue, day-of-week, content-type), and a complete reporting subsystem. The only minor gap is the absence of playlist update/delete tools, but playlist create/list/add/remove is largely covered.
Maintenance
Related MCP Connectors
YouTube for AI agents: transcripts, comments, video stats, channel monitor, Shorts captions.
Search YouTube videos, read transcripts and get public video information in your AI assistant.
YouTube transcripts, search, channel/playlist listings and upload tracking for AI agents.
YouTube transcripts, search, channels, playlists and bulk transcript jobs for AI agents. 14 tools.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI models to interact with YouTube content including video details, transcripts, channel information, playlists, and search functionality through the YouTube Data API.797 npm11MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to search videos, read channels, browse playlists, fetch comments, and get transcripts from YouTube using the YouTube Data API v3 and InnerTube API for captions.2GPL 3.0
- FlicenseNot gradedqualityDmaintenanceProvides AI assistants with comprehensive YouTube analytics and channel management capabilities, including channel performance, video analytics, audience insights, and content strategy tools.26 npm1-
- FlicenseNot gradedqualityCmaintenanceEnables AI assistants to search videos, retrieve transcripts and metadata, analyze channels, and access trending and engagement analytics for YouTube content.26 npm-