youtube-mcp-server

A local stdio MCP server that gives Claude (or any MCP client) full programmatic control over a single YouTube channel. Built with the MCP SDK, googleapis, and strict TypeScript/ESM.

---

What It Does

The server exposes ~46 tools grouped across eight domains:

Channel (4 tools)

Tool	Description
youtube_get_my_channel	Fetch full details (stats, branding, playlists) for the authenticated channel
youtube_get_channel	Fetch public details for any channel by ID, @handle, or username
youtube_update_channel_branding	Update description, keywords, country, language, or trailer video
youtube_list_channel_sections	List all sections on the channel home page

Videos (8 tools)

Tool	Description
youtube_get_video	Fetch full metadata for any video by ID
youtube_list_my_videos	List videos uploaded to the authenticated channel (paginated)
youtube_upload_video	Upload a local video file to the channel
youtube_update_video	Update title, description, tags, category, or privacy for a video
youtube_delete_video	Permanently delete a video (requires confirm: true)
youtube_set_video_thumbnail	Upload a local image file as the custom thumbnail
youtube_rate_video	Like, dislike, or remove a rating on any video
youtube_get_video_categories	List available video category IDs for a given region

Playlists (6 tools)

Tool	Description
youtube_list_my_playlists	List playlists owned by the authenticated channel
youtube_get_playlist	Fetch details for any playlist by ID
youtube_create_playlist	Create a new playlist with title, description, and privacy
youtube_update_playlist	Update title, description, or privacy of a playlist
youtube_delete_playlist	Permanently delete a playlist (requires confirm: true)
youtube_list_playlist_items	List items (videos) inside any playlist (paginated)
youtube_add_playlist_item	Add a video to a playlist
youtube_remove_playlist_item	Remove an item from a playlist (requires confirm: true)

Comments (6 tools)

Tool	Description
youtube_list_comment_threads	List top-level comment threads on a video or channel
youtube_get_comment_thread	Fetch a single comment thread with replies
youtube_add_comment	Post a new top-level comment on a video
youtube_reply_to_comment	Post a reply to an existing comment thread
youtube_update_comment	Edit the text of a comment you own
youtube_delete_comment	Delete a comment (requires confirm: true)
youtube_set_moderation_status	Set a comment's moderation status (hold/publish/reject)

Captions (5 tools)

Tool	Description
youtube_list_captions	List caption tracks for a video
youtube_download_caption	Download the raw caption track content
youtube_upload_caption	Upload a new caption file to a video
youtube_update_caption	Replace an existing caption track
youtube_delete_caption	Delete a caption track (requires confirm: true)

Search (2 tools)

Tool	Description
youtube_search	Full YouTube search with filters (type, channel, order, date, region)
youtube_search_my_videos	Search within only the authenticated channel's videos

Subscriptions (3 tools)

Tool	Description
youtube_list_subscriptions	List channels the authenticated account is subscribed to
youtube_subscribe	Subscribe to a channel by channel ID
youtube_unsubscribe	Unsubscribe from a channel (requires confirm: true)

Analytics (6 tools)

Tool	Description
youtube_get_channel_analytics	Core channel metrics (views, watchTime, subscribers) over a date range
youtube_get_video_analytics	Per-video metrics over a date range
youtube_get_traffic_sources	Traffic source breakdown (search, suggested, external, etc.)
youtube_get_audience_demographics	Age/gender audience breakdown
youtube_get_top_videos	Top N videos by a chosen metric (views, watchTimeMins, etc.)
youtube_get_revenue_analytics	Revenue and ad metrics (requires monetized channel)

---

Prerequisites

• Node.js >= 18 (ESM + fetch builtins required)
• A Google account with a YouTube channel
• A Google Cloud project (see setup below)

---

Credentials & Configuration

This server authenticates to Google as you via OAuth 2.0. Nothing is hard-coded — you supply credentials at runtime, and none of them are ever committed (all are listed in .gitignore). You need three secret values, all obtained during the Google OAuth setup below:

Value	What it is	Where it comes from
client_id	OAuth client identifier (ends in …apps.googleusercontent.com)	credentials.json, downloaded from Google Cloud Console
client_secret	OAuth client secret	credentials.json
refresh_token	Long-lived token authorizing access to your channel	produced by npm run auth (the browser consent flow)

You provide these in one of two ways:

Option A — file-based (recommended). Drop the downloaded credentials.json into the project root and run npm run auth. That writes token.json (containing all three values) and the server picks it up automatically. Nothing else to configure.

Option B — environment variables. Instead of token.json, set the three values directly (handy for CI, Docker, or a secrets manager):

YT_CLIENT_ID=your-client-id.apps.googleusercontent.com
YT_CLIENT_SECRET=your-client-secret
YT_REFRESH_TOKEN=your-refresh-token

See .env.example for a fully-commented template covering both options. Never commit credentials.json, token.json, or a real .env — anyone holding these can fully control your YouTube channel.

---

Google OAuth Setup

1. Create or Select a Google Cloud Project

1. Go to console.cloud.google.com.
2. Click the project selector (top-left) → New Project.
3. Name it (e.g. my-youtube-app), click Create.
4. Make sure the new project is selected in the dropdown before continuing.

2. Enable the Required APIs

1. In the left menu: APIs & Services → Library.
2. Search for and Enable each of the following:
   • YouTube Data API v3 (required)
   • YouTube Analytics API (required)
   • YouTube Reporting API (optional — bulk reporting jobs)

3. Configure the OAuth Consent Screen

1. Go to APIs & Services → OAuth consent screen.
2. Select External as the User Type, click Create.
3. Fill in the required fields:
   • App name (e.g. My YouTube Tool)
   • User support email (your own Google account)
   • Developer contact email (your own Google account)
4. Click Save and Continue through the Scopes step (you will add scopes in code, not here — or add them here if prompted).
5. On the Test users step: click + Add Users and add your own Google account email. Click Save and Continue.
6. Submit/finish the wizard.

Important — 7-day token expiry warning: While the app's publishing status is Testing, Google issues refresh tokens that expire after 7 days, regardless of any other setting. When your token expires, your app will get an invalid_grant error and you must re-authenticate.

To avoid this disruption:

• Option A (recommended for personal use): Keep the app in Testing but make sure your own account is listed as a Test User — re-auth when needed, or click Publish App to move to Production.
• Option B: Click Publish App → your app moves to "In Production" and refresh tokens no longer have the 7-day limit (tokens only expire if unused for 6+ months or manually revoked).

For a personal channel tool you own, publishing is safe and removes the friction.

4. Create OAuth Client Credentials (Desktop App)

1. Go to APIs & Services → Credentials.
2. Click + Create Credentials → OAuth client ID.
3. Application type: Desktop app.
4. Name it (e.g. youtube-desktop-client), click Create.
5. Click Download JSON on the confirmation dialog (or find it in the credentials list and click the download icon).
6. Save the file as credentials.json in your project root.
7. Keep this file private — never commit it to version control.

5. Scopes Requested

The server requests all six of these scopes:

https://www.googleapis.com/auth/youtube
https://www.googleapis.com/auth/youtube.force-ssl
https://www.googleapis.com/auth/youtube.upload
https://www.googleapis.com/auth/youtubepartner
https://www.googleapis.com/auth/yt-analytics.readonly
https://www.googleapis.com/auth/yt-analytics-monetary.readonly

These cover full channel management, uploads, partner operations, and read access to both standard and monetary analytics.

6. Quota Limits

Resource	Cost
Default daily quota	10,000 units/day
search.list	100 units per call
videos.insert (upload)	~1,600 units per call
Most read operations	1–5 units

Monitor usage at APIs & Services → Quotas & System Limits. You can request a quota increase via the console if needed.

7. Local Auth Flow with @google-cloud/local-auth

The npm run auth command uses @google-cloud/local-auth to open a browser consent flow and writes token.json to the project root.

import { authenticate } from '@google-cloud/local-auth';
import path from 'path';

const SCOPES = [
  'https://www.googleapis.com/auth/youtube',
  'https://www.googleapis.com/auth/youtube.force-ssl',
  'https://www.googleapis.com/auth/youtube.upload',
  'https://www.googleapis.com/auth/youtubepartner',
  'https://www.googleapis.com/auth/yt-analytics.readonly',
  'https://www.googleapis.com/auth/yt-analytics-monetary.readonly',
];

const client = await authenticate({
  scopes: SCOPES,
  keyfilePath: path.join(process.cwd(), 'credentials.json'),
});
// client.credentials includes access_token AND refresh_token

How the flow works:

1. authenticate() starts a local loopback HTTP server on localhost (a random port).
2. It opens the Google consent URL in the user's default browser.
3. After the user grants consent, Google redirects to http://localhost:<port> with an auth code.
4. The library exchanges the code for tokens and returns an OAuth2Client.
5. client.credentials.refresh_token is present on the first authorization — persist it (e.g. token.json) and reuse it to avoid re-prompting on subsequent runs.

import fs from 'fs';
const TOKEN_PATH = path.join(process.cwd(), 'token.json');

// After first auth, save credentials:
fs.writeFileSync(TOKEN_PATH, JSON.stringify(client.credentials));

// On subsequent runs, load and restore:
import { google } from 'googleapis';
const savedCreds = JSON.parse(fs.readFileSync(TOKEN_PATH, 'utf8'));
const oauth2Client = new google.auth.OAuth2();
oauth2Client.setCredentials(savedCreds);
// Pass oauth2Client to google.youtube({ version: 'v3', auth: oauth2Client })

Sources:

• OAuth 2.0 for Mobile & Desktop Apps — YouTube Data API
• Obtaining Authorization Credentials — YouTube Data API
• Using OAuth 2.0 to Access Google APIs
• OAuth 2.0 Policies (token expiry)
• OAuth 2.0 for Native Apps

---

Install and Build

# Install dependencies
npm install

# Compile TypeScript to dist/
npm run build

---

Authorize

Run the one-time OAuth flow to generate token.json:

npm run auth

This opens a browser window. Sign in with the Google account that owns your YouTube channel, grant all requested scopes, and the token is saved automatically.

Security note: credentials.json and token.json are listed in .gitignore and must never be committed or shared. Anyone with these files can fully manage your YouTube channel.

---

Connect to Claude Code

Option A — claude mcp add command

claude mcp add youtube-mcp-server \
  --transport stdio \
  -- node "/ABSOLUTE/PATH/TO/youtube-mcp-server/dist/index.js"

If you want to pass the token path explicitly via an environment variable:

claude mcp add youtube-mcp-server \
  --transport stdio \
  --env YT_TOKEN_PATH="/ABSOLUTE/PATH/TO/youtube-mcp-server/token.json" \
  -- node "/ABSOLUTE/PATH/TO/youtube-mcp-server/dist/index.js"

Option B — JSON config block

Add the following entry to your Claude Code MCP config file (.claude/settings.json or the global equivalent):

{
  "mcpServers": {
    "youtube-mcp-server": {
      "type": "stdio",
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/youtube-mcp-server/dist/index.js"],
      "env": {
        "YT_TOKEN_PATH": "/ABSOLUTE/PATH/TO/youtube-mcp-server/token.json"
      }
    }
  }
}

Option C — Environment-variable auth (no token.json)

Instead of token.json, you can supply credentials directly via environment variables — useful for CI or shared environments:

export YT_CLIENT_ID="your-client-id"
export YT_CLIENT_SECRET="your-client-secret"
export YT_REFRESH_TOKEN="your-refresh-token"
node dist/index.js

Copy .env.example to .env and fill in the values if you use a .env-loading approach.

---

Quota and Safety Notes

• Daily quota: 10,000 units by default. A single youtube_search call costs 100 units; a video upload costs ~1,600 units. Read operations cost 1–5 units each.
• Destructive tools (youtube_delete_video, youtube_delete_playlist, youtube_delete_comment, youtube_delete_caption, youtube_remove_playlist_item, youtube_unsubscribe) all require confirm: true in the call. This prevents accidental data loss when the model mis-fires.
• Revenue analytics (youtube_get_revenue_analytics) requires a monetized channel enrolled in the YouTube Partner Program.
• Token expiry: If you leave the OAuth app in "Testing" status, refresh tokens expire after 7 days. Either add yourself as a Test User and re-run npm run auth when needed, or publish the app to Production to remove the limit.

---

Testing

Interactive inspector (recommended for exploring tools)

npx @modelcontextprotocol/inspector node dist/index.js

Open the URL printed in the terminal to browse and call tools interactively.

Smoke test (CI-friendly)

npm run build
node scripts/smoke.mjs

Expected output:

TOOLS:46

Exit code 0 means at least one tool is registered; exit code 1 means the server failed to respond or registered no tools.