About

A personal MCP server that wraps the YouTube Data API v3 and YouTube Analytics API into 27 tools usable from Claude Desktop, Claude Code, or any MCP-compatible client.

Built for analyzing and growing a YouTube channel — search videos, get transcripts, track performance, monitor subscribers, analyze traffic sources, and more.

Table of Contents

• About
• Quick Start
• Google Cloud Setup
• Claude Desktop Configuration
• Available Tools
• Development

Quick Start

Prerequisites

• Node.js (v20+)
• A Google Cloud project with YouTube APIs enabled
• A YouTube API Key (for Data API)
• OAuth 2.0 credentials (for Analytics API)

Installation

1. Clone the repository

   git clone https://github.com/m6b9/mcp-youtube.git
   cd mcp-youtube
   

2. Install dependencies

   npm install
   

3. Build

   npm run build
   

Google Cloud Setup

1. Create a project

Go to Google Cloud Console and create a new project (or use an existing one).

2. Enable the APIs

Navigate to APIs & Services > Library and enable:

• YouTube Data API v3 — for video search, channel info, comments, transcripts
• YouTube Analytics API — for channel analytics, revenue, demographics

3. Create an API Key (Data API)

1. Go to APIs & Services > Credentials
2. Click Create Credentials > API Key
3. (Optional) Restrict the key to YouTube Data API v3 only
4. Copy the key

4. Create OAuth 2.0 Credentials (Analytics API)

1. Go to APIs & Services > Credentials
2. Click Create Credentials > OAuth client ID
3. If prompted, configure the OAuth consent screen first:
   • Choose External user type
   • Fill in the app name (e.g. "MCP YouTube")
   • Add your email as a test user (required while in test mode)
   • Add scopes:
     • https://www.googleapis.com/auth/yt-analytics.readonly
     • https://www.googleapis.com/auth/yt-analytics-monetary.readonly
     • https://www.googleapis.com/auth/youtube.readonly
4. Select Desktop app as the application type
5. Click Create and copy the Client ID and Client Secret

Important: While your app is in "Testing" mode, only emails added as test users in the OAuth consent screen can authenticate. Go to APIs & Services > OAuth consent screen > Test users and add your Google email.

Claude Desktop Configuration

Edit your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the youtube server:

{
  "mcpServers": {
    "youtube": {
      "command": "/path/to/node",
      "args": ["/path/to/m6b9-mcp-youtube/dist/index.js"],
      "env": {
        "YOUTUBE_API_KEY": "your-youtube-api-key",
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Then restart Claude Desktop.

First-time OAuth Login

1. Ask Claude to use the auth_status tool to verify credentials are configured
2. Ask Claude to use the auth_login tool — it will open your browser
3. Sign in with the Google account added as a test user
4. Approve the permissions
5. Tokens are stored locally in ~/.m6b9-mcp-youtube/tokens.json and auto-refresh

Available Tools

Data API (API Key) — 14 tools

| Tool | Description | |------|-------------| | search_videos | Search for YouTube videos with filters (query, date, order, channel) | | get_video | Get detailed info for one or more videos | | get_trending_videos | Get trending videos for a region | | get_video_categories | List video categories for a region | | get_related_videos | Find videos related to a given video | | get_channel | Get channel info by ID, username, or handle | | search_channels | Search for channels | | list_channel_videos | List recent videos from a channel | | get_playlist | Get playlist details | | list_playlist_items | List videos in a playlist | | list_channel_playlists | List playlists from a channel | | list_comments | List comment threads on a video | | list_comment_replies | List replies to a comment | | list_captions | List available caption tracks | | get_transcript | Get video transcript with timestamps |

Analytics API (OAuth) — 13 tools

| Tool | Description | |------|-------------| | auth_login | Authenticate with Google OAuth (opens browser) | | auth_status | Check if OAuth is configured and authenticated | | channel_overview | Views, watch time, subs, likes over time (by day/month) | | top_videos | Top performing videos by any metric | | video_analytics | Detailed daily analytics for a specific video | | audience_demographics | Age group and gender breakdown | | audience_geography | Viewer breakdown by country | | traffic_sources | Where viewers come from (search, suggested, external...) | | device_stats | Device type breakdown (mobile, desktop, tablet, TV) | | revenue_report | Revenue, CPM, monetized playbacks (by day/month/video) | | content_type_performance | Shorts vs long-form vs live comparison | | subscriber_changes | Subscriber gains and losses over time | | playback_locations | Where videos are watched (YouTube, embedded, etc.) |

Development

# Run in dev mode (TypeScript, no build needed)
YOUTUBE_API_KEY=xxx GOOGLE_CLIENT_ID=xxx GOOGLE_CLIENT_SECRET=xxx npm run dev

# Build for production
npm run build

# Run production build
YOUTUBE_API_KEY=xxx node dist/index.js

Project Structure

src/
├── index.ts              # MCP server bootstrap
├── client.ts             # YouTube Data API client (API key)
├── analytics-client.ts   # YouTube Analytics API client (OAuth)
├── auth.ts               # OAuth 2.0 flow + token management
└── tools/
    ├── videos.ts         # Video search, details, trending
    ├── channels.ts       # Channel info, search, videos
    ├── playlists.ts      # Playlist management
    ├── comments.ts       # Comment threads and replies
    ├── captions.ts       # Captions and transcripts
    ├── auth.ts           # Login and status tools
    └── analytics.ts      # All analytics/reporting tools

Tech Stack

• Runtime: Node.js 20+
• Language: TypeScript (ESM)
• MCP SDK: @modelcontextprotocol/sdk
• Validation: Zod
• Build: tsup
• Dev: tsx