maagpi-youtube-mcp

maagpi-youtube-mcp is a full YouTube channel-management MCP server: upload videos, schedule publishing, query analytics, moderate comments, manage playlists, update channel branding, and operate multiple YouTube channels simultaneously — all from any MCP-compatible AI client.

Wraps the official YouTube Data API v3 + YouTube Analytics API behind a single MCP surface with built-in OAuth, quota tracking, response caching, and structured error handling.

Transport

• Default: stdio (local process, spawned by your MCP client)
• Optional: Streamable HTTP (YOUTUBE_MCP_TRANSPORT=http) for multi-client / remote access
• Distribution: npx maagpi-youtube-mcp — no global install required
• Full docs: see Tool Reference below

Authentication

This server uses Google OAuth 2.0 (Desktop app credentials). You provide a Client ID + Client Secret as environment variables; the server handles the browser consent flow and stores refresh tokens to your OS config directory under named profiles (one per channel).

One-time Google Cloud setup

1. Google Cloud Console → APIs & Services → Library → enable:
   • YouTube Data API v3
   • YouTube Analytics API
2. APIs & Services → OAuth consent screen → External → fill app name + your email → add your Google account as a Test user.
3. APIs & Services → Credentials → Create Credentials → OAuth client ID → Application type Desktop app → copy the Client ID and Client Secret.

Keep your Client Secret out of source control. The server never transmits it anywhere except accounts.google.com.

First call: the server opens a browser window for OAuth consent. Approve once, and tokens are saved automatically under the "default" profile and auto-refreshed thereafter. Add more channels with youtube_account_add.

Quick Connect

Pick your client and drop the snippet into the corresponding config file. Replace your_client_id / your_client_secret with your Google OAuth credentials.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) %APPDATA%\Claude\claude_desktop_config.json (Windows)

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "maagpi-youtube-mcp"],
      "env": {
        "YOUTUBE_CLIENT_ID": "your_client_id",
        "YOUTUBE_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Claude Code

~/.claude/settings.json

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "maagpi-youtube-mcp"],
      "env": {
        "YOUTUBE_CLIENT_ID": "your_client_id",
        "YOUTUBE_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Or via the Claude Code CLI:

claude mcp add youtube -- npx -y maagpi-youtube-mcp \
  -e YOUTUBE_CLIENT_ID=your_client_id \
  -e YOUTUBE_CLIENT_SECRET=your_client_secret

Cursor

~/.cursor/mcp.json

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "maagpi-youtube-mcp"],
      "env": {
        "YOUTUBE_CLIENT_ID": "your_client_id",
        "YOUTUBE_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "maagpi-youtube-mcp"],
      "env": {
        "YOUTUBE_CLIENT_ID": "your_client_id",
        "YOUTUBE_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

VS Code (MCP-compatible extensions)

.vscode/mcp.json (workspace) or User Settings:

{
  "servers": {
    "youtube": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "maagpi-youtube-mcp"],
      "env": {
        "YOUTUBE_CLIENT_ID": "your_client_id",
        "YOUTUBE_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Zed

~/.config/zed/settings.json

{
  "context_servers": {
    "youtube": {
      "command": {
        "path": "npx",
        "args": ["-y", "maagpi-youtube-mcp"],
        "env": {
          "YOUTUBE_CLIENT_ID": "your_client_id",
          "YOUTUBE_CLIENT_SECRET": "your_client_secret"
        }
      }
    }
  }
}

mcporter

mcporter add youtube --command "npx -y maagpi-youtube-mcp" \
  --env YOUTUBE_CLIENT_ID=your_client_id \
  --env YOUTUBE_CLIENT_SECRET=your_client_secret

mcporter call youtube youtube_account_list '{}'

Streamable HTTP (remote / multi-client)

Run the server as an HTTP service:

YOUTUBE_MCP_TRANSPORT=http \
YOUTUBE_MCP_HTTP_PORT=3000 \
YOUTUBE_CLIENT_ID=your_client_id \
YOUTUBE_CLIENT_SECRET=your_client_secret \
npx -y maagpi-youtube-mcp
# MCP endpoint: POST http://127.0.0.1:3000/mcp
# Health check: GET  http://127.0.0.1:3000/health

Then point any HTTP-capable MCP client at http://127.0.0.1:3000/mcp.

Tool Reference

All tools accept an optional channel parameter (profile name). Omit it to use the active profile.

Account Management

Tool	Parameters	Description
youtube_account_add	name	Connect a new channel via OAuth, save as a named profile
youtube_account_list	none	List all connected profiles with IDs and active status
youtube_account_switch	name	Set the default active profile
youtube_account_current	none	Show the currently active profile
youtube_account_remove	name, confirm: true	Disconnect and remove a profile

Videos

Tool	Parameters	Quota
youtube_video_upload	filePath, title, privacyStatus, channel?	1600
youtube_video_get	videoId, parts?, channel?	1
youtube_video_list	channelId?, query?, order?, maxResults?, channel?	1
youtube_video_update	videoId, title?, description?, tags?, channel?	50
youtube_video_delete	videoId, confirm: true, channel?	50
youtube_video_rate	videoId, rating (like/dislike/none), channel?	50
youtube_video_set_thumbnail	videoId, thumbnailPath, channel?	50

Scheduling & Publishing

Tool	Parameters	Quota
youtube_video_set_privacy	videoId, privacyStatus, channel?	50
youtube_video_schedule_publish	videoId, publishAt (future ISO 8601), channel?	50
youtube_video_set_premiere	videoId, premiereAt (future ISO 8601), channel?	50

Analytics

Tool	Parameters	Quota
youtube_analytics_video_metrics	videoId, startDate, endDate, metrics[], channel?	1
youtube_analytics_channel_metrics	startDate, endDate, metrics[], channel?	1
youtube_analytics_top_videos	startDate, endDate, metric, maxResults?, channel?	1
youtube_analytics_audience_retention	videoId, startDate, endDate, channel?	1
youtube_analytics_revenue_report	startDate, endDate, dimensions?, channel?	1

Dates use YYYY-MM-DD. Common video metrics: views, watchTime, averageViewDuration, averageViewPercentage, likes, shares, subscribersGained, subscribersLost. Channel metrics add estimatedRevenue, estimatedAdRevenue, grossRevenue, monetizedPlaybacks, cpm, adImpressions.

Comments

Tool	Parameters	Quota
youtube_comment_list	videoId, maxResults?, order?, searchTerms?, channel?	1
youtube_comment_thread_get	commentThreadId, maxReplies?, channel?	1
youtube_comment_reply	parentCommentId, text, channel?	50
youtube_comment_delete	commentId, channel?	50
youtube_comment_moderate	commentId, moderationStatus (published/heldForReview/rejected), banAuthor?, channel?	50

Playlists

Tool	Parameters	Quota
youtube_playlist_create	title, privacyStatus, channel?	50
youtube_playlist_update	playlistId, title?, description?, channel?	50
youtube_playlist_delete	playlistId, confirm: true, channel?	50
youtube_playlist_get	playlistId, channel?	1
youtube_playlist_list	channelId?, maxResults?, channel?	1
youtube_playlist_item_add	playlistId, videoId, position?, channel?	50
youtube_playlist_item_remove	playlistItemId, channel?	50
youtube_playlist_item_reorder	playlistItemId, playlistId, newPosition, channel?	50
youtube_playlist_items_list	playlistId, maxResults?, channel?	1

Channel Management

Tool	Parameters	Quota
youtube_channel_get	parts?, channel?	1
youtube_channel_update	title?, description?, keywords?, country?, channel?	50
youtube_channel_branding_update	showRelatedChannels?, featuredChannelsTitle?, channel?	50
youtube_channel_watermark_set	channelId, imagePath, position, timing, channel?	50
youtube_channel_watermark_unset	channelId, channel?	50
youtube_channel_section_list	channelId?, channel?	1
youtube_channel_section_create	type, title?, playlistIds?, channel?	50
youtube_channel_section_delete	sectionId, channel?	50

Example Prompts

Once connected, send these to your AI client as natural language:

Upload /videos/tutorial.mp4 with title "Getting Started with TypeScript",
description "A beginner's guide", tags ["typescript","programming"], unlisted.

Schedule video dQw4w9WgXcQ to go public on January 20 2026 at 3pm UTC.

Get top 5 videos by views in Q1 2025 for my "main" channel,
and also for my "gaming" channel.

Show me revenue breakdown for 2025-01-01 to 2025-01-31, split by day.

Reply to comment Ugxxxxx with "Thanks for the feedback! Fixed in v2."

Tools that delete data require confirm: true — your AI client will ask before proceeding.

Multiple Channels

Connect any number of YouTube accounts and target any of them from any tool via the optional channel parameter — no switching required.

Add a new YouTube channel profile named "gaming"
List all my connected YouTube channel profiles
Switch my active YouTube profile to "gaming"
Upload /videos/clip.mp4 to my "gaming" channel, title "EP1", public

CLI auth for a named profile (handy for headless setups):

npm run auth -- --channel gaming

Quota

YouTube Data API v3 grants 10,000 units/day by default. Every tool response includes a quota field:

{
  "quota": {
    "used": 151,
    "budget": 9000,
    "remaining": 8849,
    "resetAt": "2026-01-15T08:00:00.000Z",
    "warningLevel": "ok",
    "costOfThisCall": 1
  }
}

warningLevel: "ok" → "warn" at 80% → "critical" at 95%.

Built-in protections

• GET responses are cached (videos 60s, channels 5min, analytics 5min) — repeat reads cost 0 quota
• Writes auto-retry on 429/5xx with exponential backoff (up to 3×)
• Set YOUTUBE_MCP_QUOTA_LIMIT below 10,000 to leave headroom

Error Format

All errors are returned as structured tool content — agents can read and act on them without crashing:

{
  "success": false,
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "YouTube API daily quota has been exceeded.",
    "suggestedFix": "Wait for quota reset at midnight Pacific Time, or increase your quota in Google Cloud Console.",
    "retryable": false,
    "docsUrl": "https://developers.google.com/youtube/v3/getting-started#quota"
  },
  "quota": { "used": 9001, "warningLevel": "critical" }
}

Code	Meaning
AUTH_REQUIRED	No stored tokens — OAuth flow needed
AUTH_TOKEN_EXPIRED	Token expired and refresh failed — re-authenticate
AUTH_INSUFFICIENT_SCOPE	Missing OAuth scope — delete tokens and re-auth
QUOTA_EXCEEDED	Daily quota exhausted — wait for midnight PT reset
PERMISSION_DENIED	Resource not owned by authenticated account
VIDEO_NOT_FOUND	Video ID doesn't exist or isn't accessible
PLAYLIST_NOT_FOUND	Playlist ID not found
RATE_LIMITED	Temporary rate limit — server retries automatically
INVALID_PARAMS	Zod validation failed — check parameter types
PUBLISH_DATE_IN_PAST	publishAt / premiereAt must be a future datetime

Environment Variables

Variable	Required	Default	Description
YOUTUBE_CLIENT_ID	✓	—	Google OAuth2 client ID
YOUTUBE_CLIENT_SECRET	✓	—	Google OAuth2 client secret
YOUTUBE_MCP_TRANSPORT		stdio	stdio or http
YOUTUBE_MCP_HTTP_PORT		3000	HTTP server port
YOUTUBE_MCP_HTTP_HOST		127.0.0.1	HTTP bind address
YOUTUBE_MCP_QUOTA_LIMIT		9000	Daily quota warning threshold
YOUTUBE_MCP_CACHE_TTL		per-resource	Override all cache TTLs (ms)
YOUTUBE_MCP_LOG_LEVEL		info	error | warn | info | debug

Development

npm install
npm run dev          # run with tsx (requires .env)
npm run auth         # authenticate the default channel profile
npm run auth -- --channel gaming   # authenticate a named profile
npm run typecheck    # tsc --noEmit
npm test             # vitest unit tests
npm run build        # production bundle → dist/index.js
npm pack --dry-run   # verify publish artifact

Why maagpi-youtube-mcp 🎯

• Operate YouTube from any AI client — Claude, Cursor, Windsurf, Zed, VS Code, mcporter
• Manage multiple channels at once — no context switching, target any channel per call
• Production-grade plumbing — OAuth, refresh tokens, quota tracking, retries, structured errors
• Full surface coverage — videos, scheduling, analytics, comments, playlists, branding

Links

• npm: https://www.npmjs.com/package/maagpi-youtube-mcp
• YouTube Data API: https://developers.google.com/youtube/v3
• YouTube Analytics API: https://developers.google.com/youtube/analytics
• Model Context Protocol: https://modelcontextprotocol.io