maagpi-youtube-mcp

https://github.com/vamsi-kodimela/maagpi-youtube-mcp

GitHub

maagpi-youtube-mcp

MCP npm node

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

ToolParametersDescription
youtube_account_addnameConnect a new channel via OAuth, save as a named profile
youtube_account_listnoneList all connected profiles with IDs and active status
youtube_account_switchnameSet the default active profile
youtube_account_currentnoneShow the currently active profile
youtube_account_removename, confirm: trueDisconnect and remove a profile

Videos

ToolParametersQuota
youtube_video_uploadfilePath, title, privacyStatus, channel?1600
youtube_video_getvideoId, parts?, channel?1
youtube_video_listchannelId?, query?, order?, maxResults?, channel?1
youtube_video_updatevideoId, title?, description?, tags?, channel?50
youtube_video_deletevideoId, confirm: true, channel?50
youtube_video_ratevideoId, rating (like/dislike/none), channel?50
youtube_video_set_thumbnailvideoId, thumbnailPath, channel?50

Scheduling & Publishing

ToolParametersQuota
youtube_video_set_privacyvideoId, privacyStatus, channel?50
youtube_video_schedule_publishvideoId, publishAt (future ISO 8601), channel?50
youtube_video_set_premierevideoId, premiereAt (future ISO 8601), channel?50

Analytics

ToolParametersQuota
youtube_analytics_video_metricsvideoId, startDate, endDate, metrics[], channel?1
youtube_analytics_channel_metricsstartDate, endDate, metrics[], channel?1
youtube_analytics_top_videosstartDate, endDate, metric, maxResults?, channel?1
youtube_analytics_audience_retentionvideoId, startDate, endDate, channel?1
youtube_analytics_revenue_reportstartDate, 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

ToolParametersQuota
youtube_comment_listvideoId, maxResults?, order?, searchTerms?, channel?1
youtube_comment_thread_getcommentThreadId, maxReplies?, channel?1
youtube_comment_replyparentCommentId, text, channel?50
youtube_comment_deletecommentId, channel?50
youtube_comment_moderatecommentId, moderationStatus (published/heldForReview/rejected), banAuthor?, channel?50

Playlists

ToolParametersQuota
youtube_playlist_createtitle, privacyStatus, channel?50
youtube_playlist_updateplaylistId, title?, description?, channel?50
youtube_playlist_deleteplaylistId, confirm: true, channel?50
youtube_playlist_getplaylistId, channel?1
youtube_playlist_listchannelId?, maxResults?, channel?1
youtube_playlist_item_addplaylistId, videoId, position?, channel?50
youtube_playlist_item_removeplaylistItemId, channel?50
youtube_playlist_item_reorderplaylistItemId, playlistId, newPosition, channel?50
youtube_playlist_items_listplaylistId, maxResults?, channel?1

Channel Management

ToolParametersQuota
youtube_channel_getparts?, channel?1
youtube_channel_updatetitle?, description?, keywords?, country?, channel?50
youtube_channel_branding_updateshowRelatedChannels?, featuredChannelsTitle?, channel?50
youtube_channel_watermark_setchannelId, imagePath, position, timing, channel?50
youtube_channel_watermark_unsetchannelId, channel?50
youtube_channel_section_listchannelId?, channel?1
youtube_channel_section_createtype, title?, playlistIds?, channel?50
youtube_channel_section_deletesectionId, 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" }
}
CodeMeaning
AUTH_REQUIREDNo stored tokens — OAuth flow needed
AUTH_TOKEN_EXPIREDToken expired and refresh failed — re-authenticate
AUTH_INSUFFICIENT_SCOPEMissing OAuth scope — delete tokens and re-auth
QUOTA_EXCEEDEDDaily quota exhausted — wait for midnight PT reset
PERMISSION_DENIEDResource not owned by authenticated account
VIDEO_NOT_FOUNDVideo ID doesn't exist or isn't accessible
PLAYLIST_NOT_FOUNDPlaylist ID not found
RATE_LIMITEDTemporary rate limit — server retries automatically
INVALID_PARAMSZod validation failed — check parameter types
PUBLISH_DATE_IN_PASTpublishAt / premiereAt must be a future datetime

Environment Variables

VariableRequiredDefaultDescription
YOUTUBE_CLIENT_ID✓—Google OAuth2 client ID
YOUTUBE_CLIENT_SECRET✓—Google OAuth2 client secret
YOUTUBE_MCP_TRANSPORTstdiostdio or http
YOUTUBE_MCP_HTTP_PORT3000HTTP server port
YOUTUBE_MCP_HTTP_HOST127.0.0.1HTTP bind address
YOUTUBE_MCP_QUOTA_LIMIT9000Daily quota warning threshold
YOUTUBE_MCP_CACHE_TTLper-resourceOverride all cache TTLs (ms)
YOUTUBE_MCP_LOG_LEVELinfoerror | 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

相關伺服器

NotebookLM 網頁匯入器

一鍵將網頁和 YouTube 影片匯入 NotebookLM。超過 200,000 位使用者信賴。

安裝 Chrome 擴充功能