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)

Videos (8 tools)

Playlists (6 tools)

Comments (6 tools)

Captions (5 tools)

Search (2 tools)

Subscriptions (3 tools)

Analytics (6 tools)

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:

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

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.