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