Skip to main content
Glama

Fork note (felipefontoura): patched the transcript scraper for youtube-transcript-api>=1.0.0. Upstream 0.1.0 declared >=1.0.0 but still called the removed 0.6.x YouTubeTranscriptApi.list_transcripts() / dict-style snippets, so youtube_get_transcript always errored. Now uses YouTubeTranscriptApi().list() + .fetch().to_raw_data(). See src/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-api fallback for any public video

  • Quota 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

  1. Go to Google Cloud Console

  2. 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

  1. Go to APIs & Services > OAuth consent screen

  2. Set User Type to External

  3. Fill in the app name and required fields

  4. 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

  1. Go to APIs & Services > Credentials

  2. Click Create Credentials > OAuth client ID

  3. Application type: Desktop app

  4. Download the JSON file

  5. 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

youtube.force-ssl

comments and captions — mandatory, no alternative

youtube.readonly

reading videos, channels, playlists

youtube.upload

uploading videos

yt-analytics.readonly

Analytics queries

yt-analytics-monetary.readonly

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-ssl is 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-mcp

Or with uv:

uv pip install youtube-studio-mcp

MCP 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

youtube_auth

Initiate OAuth 2.0 flow

youtube_auth_status

Check auth state and quota usage

Channel & Video (3 tools)

Tool

Description

youtube_get_channel

Get channel details by ID, handle, or mine=True

youtube_list_videos

List videos from a channel or playlist

youtube_get_video

Get detailed video metadata and stats

Search & SEO (4 tools)

Tool

Description

youtube_search

Search YouTube (100 quota units per call)

youtube_search_suggestions

Get autocomplete suggestions (no quota cost)

youtube_trending

Get trending videos by region/category

youtube_get_categories

List video categories for a region

Transcripts (2 tools)

Tool

Description

youtube_get_transcript

Get video transcript (official API or scraping fallback)

youtube_list_captions

List caption tracks for own videos

Analytics — Performance (4 tools)

Tool

Description

youtube_analytics_overview

Channel summary (views, watch time, subs, likes)

youtube_analytics_top_videos

Top videos by views (excludes Shorts)

youtube_analytics_top_shorts

Top Shorts by views

youtube_analytics_video_detail

Daily metrics for a specific video

Analytics — Audience (3 tools)

Tool

Description

youtube_analytics_traffic_sources

Traffic source breakdown

youtube_analytics_demographics

Age and gender breakdown

youtube_analytics_geography

Views by country

Analytics — Schedule & Reach (3 tools)

Tool

Description

youtube_analytics_daily

Daily performance over time

youtube_analytics_day_of_week

Average performance by weekday

youtube_analytics_content_type_breakdown

Shorts vs long-form vs live comparison

Analytics — Revenue & Retention (3 tools)

Tool

Description

youtube_analytics_revenue

Revenue breakdown (requires YouTube Partner Program)

youtube_analytics_revenue_by_video

Per-video revenue

youtube_analytics_retention

Audience retention curve for a video

Publishing (4 tools)

Tool

Description

youtube_upload_video

Upload a video (1,600 quota units)

youtube_update_video

Update video metadata

youtube_set_thumbnail

Upload custom thumbnail

youtube_delete_video

Delete a video

Playlists (4 tools)

Tool

Description

youtube_list_playlists

List playlists for a channel

youtube_create_playlist

Create a new playlist

youtube_add_to_playlist

Add a video to a playlist

youtube_remove_from_playlist

Remove a video from a playlist

Comments (3 tools)

Tool

Description

youtube_list_comments

List comments on a video

youtube_post_comment

Post a top-level comment

youtube_reply_to_comment

Reply to a comment

Bulk Reporting (5 tools)

Tool

Description

youtube_reporting_list_types

List available report types

youtube_reporting_create_job

Schedule a daily report job

youtube_reporting_list_jobs

List active reporting jobs

youtube_reporting_list_reports

List generated reports for a job

youtube_reporting_download

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

YOUTUBE_MCP_CLIENT_SECRET

Path to client_secret.json

YOUTUBE_MCP_CONFIG_DIR

Config directory (default: ~/.youtube-mcp)

YOUTUBE_API_KEY

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/ -v

License

MIT

Available Tools

40 tools
youtube_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_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_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

    B3.3/5.0

    Scored across 40 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness5/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      2
      GPL 3.0
    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides AI assistants with comprehensive YouTube analytics and channel management capabilities, including channel performance, video analytics, audience insights, and content strategy tools.
      26 npm
      1
      -
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to search videos, retrieve transcripts and metadata, analyze channels, and access trending and engagement analytics for YouTube content.
      26 npm
      -