mcp-youtube-analytics 0.1.0

A Model Context Protocol (MCP) server for querying and analyzing YouTube channel performance data.

mcp-youtube-analytics

An MCP server for retrieving channel analytics through the YouTube Analytics API.

繁體中文

Available MCP Tools

Tool	Description
channel_overview	Overall channel KPIs: views, watch time, subscriber delta, and engagement
top_videos	Top-performing videos by views, including title, thumbnail, and other metadata
daily_trends	Daily trend data for spotting peaks and drawing charts
traffic_sources	Traffic source breakdown: search, suggested videos, external links, and more
top_countries	Top audience countries
top_subscriber_sources	Videos that drove the most subscribers
video_retention	Audience retention curve for a specific video
playlist_performance	Traffic and watch performance by playlist

All tools support custom start_date and end_date values in YYYY-MM-DD format. The default range is the last 30 days.

Setup

1. Create a Google Cloud project

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Under APIs & Services → Library, enable these APIs:
   • YouTube Analytics API
   • YouTube Data API v3

2. Configure the OAuth consent screen

1. Go to APIs & Services → OAuth consent screen
2. Choose External as the user type
3. Fill in the basic app information and save
4. Add your Google account under Test users so you can authorize the app before publishing

3. Create an OAuth client ID

1. Go to APIs & Services → Credentials
2. Click Create Credentials → OAuth client ID
3. Choose Desktop app as the application type
4. Download the generated JSON file
5. Rename it to client_secrets.json and place it in the project root

4. Install dependencies and run

uv sync
uv run mcp-youtube-analytics

On first run, the app opens a browser window for Google authorization. After authorization succeeds, token.json is stored in the project root and reused on later runs.

Development Testing

Use the built-in CLI tester to exercise each API function individually. All results are printed as JSON.

# Show all available commands
uv run mcp-youtube-analytics-debug --help

# Get the channel ID
uv run mcp-youtube-analytics-debug channel-id

# Overall channel performance for the default last-30-days window
uv run mcp-youtube-analytics-debug channel-overview

# Custom date range
uv run mcp-youtube-analytics-debug channel-overview --start-date 2026-01-01 --end-date 2026-01-31

# Top 5 videos by views
uv run mcp-youtube-analytics-debug top-videos --max-results 5

# Daily trend data
uv run mcp-youtube-analytics-debug daily-trends

# Traffic source breakdown
uv run mcp-youtube-analytics-debug traffic-sources

# Top audience countries
uv run mcp-youtube-analytics-debug top-countries --max-results 10

# Videos that drove the most subscribers
uv run mcp-youtube-analytics-debug top-subscriber-sources

# Retention curve for a specific video
uv run mcp-youtube-analytics-debug video-retention --video-id <VIDEO_ID>

# Playlist performance
uv run mcp-youtube-analytics-debug playlist-performance

# Fetch metadata for multiple videos
uv run mcp-youtube-analytics-debug video-metadata --ids <ID1>,<ID2>

Notes

• client_secrets.json and token.json are already listed in .gitignore; do not commit them.