> **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](https://modelcontextprotocol.io/) 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 |

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

### 3. Configure OAuth Consent Screen

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:

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

```bash
pip install youtube-studio-mcp
```

Or with uv:

```bash
uv pip install youtube-studio-mcp
```

## MCP Client Configuration

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "youtube": {
      "command": "youtube-studio-mcp"
    }
  }
}
```

### Claude Code

Add to your MCP settings:

```json
{
  "mcpServers": {
    "youtube": {
      "command": "youtube-studio-mcp"
    }
  }
}
```

### With environment variables

```json
{
  "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

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