Metadata-Version: 2.4
Name: mcp-youtube-analytics
Version: 0.1.0
Summary: A Model Context Protocol (MCP) server for querying and analyzing YouTube channel performance data.
Requires-Python: >=3.14
Requires-Dist: fastmcp>=3.2.4
Requires-Dist: google-api-python-client>=2.0.0
Requires-Dist: google-auth-httplib2>=0.2.0
Requires-Dist: google-auth-oauthlib>=1.0.0
Description-Content-Type: text/markdown

# mcp-youtube-analytics

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

[繁體中文](README.zh-tw.md)

## 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](https://console.cloud.google.com)
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

```bash
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.

```bash
# 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.
