youtube-mcp

MCP server wrapping the YouTube Data API v3 for AI agents. Provides 48 tools covering playlists, videos, channels, comments, captions, subscriptions, and more.

Built with Agent Context Protocol

Features

• 48 MCP tools covering the YouTube Data API v3
• OAuth 2.0 authentication with automatic token refresh
• Dual transport: stdio (default) and Streamable HTTP
• Quota-aware: every tool description includes its API quota cost
• Streaming uploads: video, caption, banner, thumbnail, and watermark uploads use streaming
• Retry logic: automatic retry with exponential backoff for transient errors
• Error mapping: clear, actionable error messages for all API errors

Quick Start

1. Install

npm install
npm run build

2. Configure OAuth

Set these environment variables:

GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_REDIRECT_URI=http://localhost:3000/callback

3. Run

# stdio transport (default)
npm start

# HTTP transport
node dist/index.js --transport http --port 3000

4. Claude Desktop Configuration

{
  "mcpServers": {
    "youtube": {
      "command": "node",
      "args": ["/path/to/youtube-mcp/dist/index.js"]
    }
  }
}

Transport Options

| Transport | Flag | Default | |-----------|------|---------| | stdio | --transport stdio | Yes | | HTTP | --transport http | No |

HTTP Transport Options

| Option | CLI | Env Var | Default | |--------|-----|---------|---------| | Port | --port 3000 | HTTP_PORT | 3000 | | Host | --host 0.0.0.0 | HTTP_HOST | 0.0.0.0 |

Tools Reference

Playlists (4 tools)

| Tool | Description | Quota | |------|-------------|-------| | youtube_playlists_list | List playlists by channel, ID, or authenticated user | 1 | | youtube_playlists_insert | Create a new playlist | 50 | | youtube_playlists_update | Update playlist title, description, privacy | 50 | | youtube_playlists_delete | Delete a playlist | 50 |

Playlist Items (4 tools)

| Tool | Description | Quota | |------|-------------|-------| | youtube_playlist_items_list | List items in a playlist | 1 | | youtube_playlist_items_insert | Add a video to a playlist | 50 | | youtube_playlist_items_update | Update item position or video | 50 | | youtube_playlist_items_delete | Remove an item from a playlist | 50 |

Search (1 tool)

| Tool | Description | Quota | |------|-------------|-------| | youtube_search | Search for videos, channels, or playlists | 100 |

Videos (6 tools)

| Tool | Description | Quota | |------|-------------|-------| | youtube_videos_list | List videos by ID, chart, or user rating | 1 | | youtube_videos_insert | Upload a video (streaming) | 1600 | | youtube_videos_update | Update video metadata | 50 | | youtube_videos_delete | Delete a video | 50 | | youtube_videos_rate | Rate a video (like/dislike/none) | 50 | | youtube_videos_get_rating | Get user's rating for videos | 1 |

Channels (2 tools)

| Tool | Description | Quota | |------|-------------|-------| | youtube_channels_list | List channels by ID, username, or authenticated user | 1 | | youtube_channels_update | Update channel description, keywords, language | 50 |

Subscriptions (3 tools)

| Tool | Description | Quota | |------|-------------|-------| | youtube_subscriptions_list | List subscriptions | 1 | | youtube_subscriptions_insert | Subscribe to a channel | 50 | | youtube_subscriptions_delete | Unsubscribe | 50 |

Comment Threads (2 tools)

| Tool | Description | Quota | |------|-------------|-------| | youtube_comment_threads_list | List top-level comments on a video | 1 | | youtube_comment_threads_insert | Post a new top-level comment | 50 |

Comments (5 tools)

| Tool | Description | Quota | |------|-------------|-------| | youtube_comments_list | List replies to a comment | 1 | | youtube_comments_insert | Reply to a comment | 50 | | youtube_comments_update | Edit a comment | 50 | | youtube_comments_delete | Delete a comment | 50 | | youtube_comments_moderate | Set moderation status (publish/hold/reject) | 50 |

Captions (5 tools)

| Tool | Description | Quota | |------|-------------|-------| | youtube_captions_list | List caption tracks for a video | 50 | | youtube_captions_insert | Upload a caption file (SRT/VTT) | 400 | | youtube_captions_update | Update a caption track | 450 | | youtube_captions_download | Download caption content as text | 200 | | youtube_captions_delete | Delete a caption track | 50 |

Channel Sections (4 tools)

| Tool | Description | Quota | |------|-------------|-------| | youtube_channel_sections_list | List channel homepage sections | 1 | | youtube_channel_sections_insert | Create a section | 50 | | youtube_channel_sections_update | Update section title/position | 50 | | youtube_channel_sections_delete | Delete a section | 50 |

Channel Banners (1 tool)

| Tool | Description | Quota | |------|-------------|-------| | youtube_channel_banners_insert | Upload a channel banner image | 50 |

Thumbnails (1 tool)

| Tool | Description | Quota | |------|-------------|-------| | youtube_thumbnails_set | Set a custom video thumbnail | 50 |

Watermarks (2 tools)

| Tool | Description | Quota | |------|-------------|-------| | youtube_watermarks_set | Set channel watermark overlay | 50 | | youtube_watermarks_unset | Remove channel watermark | 50 |

Activities (1 tool)

| Tool | Description | Quota | |------|-------------|-------| | youtube_activities_list | List channel activities | 1 |

Members (2 tools)

| Tool | Description | Quota | |------|-------------|-------| | youtube_members_list | List channel members/sponsors | 1 | | youtube_memberships_levels_list | List membership levels | 1 |

i18n (2 tools)

| Tool | Description | Quota | |------|-------------|-------| | youtube_i18n_languages_list | List supported languages | 1 | | youtube_i18n_regions_list | List supported regions | 1 |

Video Categories (1 tool)

| Tool | Description | Quota | |------|-------------|-------| | youtube_video_categories_list | List video categories by region | 1 |

Abuse Reporting (2 tools)

| Tool | Description | Quota | |------|-------------|-------| | youtube_video_abuse_report_reasons_list | List valid abuse report reasons | 1 | | youtube_videos_report_abuse | Report a video for abuse | 50 |

Quota Budgeting

The YouTube Data API has a daily quota of 10,000 units by default. Key costs:

| Operation | Cost | |-----------|------| | Most list/read operations | 1 unit | | Search | 100 units | | Insert/Update/Delete (most) | 50 units | | Caption insert | 400 units | | Caption update | 450 units | | Caption download | 200 units | | Caption list | 50 units | | Video upload | 1600 units |

OAuth Scopes

| Scope | Used By | |-------|---------| | youtube.readonly | All list/read operations | | youtube | Playlist, video, channel, subscription writes | | youtube.upload | Video uploads | | youtube.force-ssl | Comments, captions, moderation |

Development

npm run dev        # Watch mode with tsx
npm run build      # Production build with esbuild
npm test           # Run tests (101 passing)
npm run typecheck  # TypeScript type checking

Project Structure

youtube-mcp/
├── src/
│   ├── index.ts              # Entry point (transport selection)
│   ├── server.ts             # MCP server factory
│   ├── auth/oauth.ts         # OAuth 2.0 authentication
│   ├── client/youtube.ts     # YouTube API client wrapper
│   ├── tools/                # 18 tool modules
│   └── transport/http.ts     # Streamable HTTP transport
├── tests/
│   ├── unit/                 # 16 test suites
│   └── helpers/              # Mock client, fixtures
├── agent/                    # ACP project management
└── dist/                     # Built output

License

MIT

Author

Patrick Michaelsen