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:

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

Videos

Scheduling & Publishing

Analytics

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

Playlists

Channel Management

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" }
}

Environment Variables

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