npm package: @node2flow/youtube-mcp
Description: MCP server for YouTube Data API v3 — search, videos, channels, playlists, comments, and more through 20 tools
Author: Node2Flow
Latest version: 1.0.1

# YouTube MCP Server

[![smithery badge](https://smithery.ai/badge/node2flow/youtube)](https://smithery.ai/server/node2flow/youtube)
[![npm version](https://img.shields.io/npm/v/@node2flow/youtube-mcp.svg)](https://www.npmjs.com/package/@node2flow/youtube-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

MCP server for YouTube Data API v3 — search videos, get channel info, manage playlists, post comments, and more through 20 tools.

## Quick Start

### Claude Desktop / Cursor (stdio)

```json
{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "@node2flow/youtube-mcp"],
      "env": {
        "YOUTUBE_CLIENT_ID": "your_client_id",
        "YOUTUBE_CLIENT_SECRET": "your_client_secret",
        "YOUTUBE_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}
```

### HTTP Mode

```bash
YOUTUBE_CLIENT_ID=id YOUTUBE_CLIENT_SECRET=secret YOUTUBE_REFRESH_TOKEN=token npx @node2flow/youtube-mcp --http
# → http://localhost:3000/mcp
```

### Cloudflare Worker

```
https://youtube-mcp-community.node2flow.net/mcp?YOUTUBE_CLIENT_ID=id&YOUTUBE_CLIENT_SECRET=secret&YOUTUBE_REFRESH_TOKEN=token
```

## Configuration

| Variable | Required | Description |
|----------|----------|-------------|
| `YOUTUBE_CLIENT_ID` | Yes | OAuth 2.0 Client ID from [Google Cloud Console](https://console.developers.google.com/) |
| `YOUTUBE_CLIENT_SECRET` | Yes | OAuth 2.0 Client Secret |
| `YOUTUBE_REFRESH_TOKEN` | Yes | OAuth 2.0 Refresh Token (server auto-refreshes access tokens) |

### How to Get Credentials

1. Go to [Google Cloud Console](https://console.developers.google.com/)
2. Create a project → Enable **YouTube Data API v3**
3. Go to **Credentials** → Create **OAuth 2.0 Client ID** (Desktop app or Web application)
4. Note down **Client ID** and **Client Secret**
5. Get a **Refresh Token** using [OAuth 2.0 Playground](https://developers.google.com/oauthplayground/):
   - Click gear icon → Check **"Use your own OAuth credentials"** → Enter your Client ID & Secret
   - In Step 1, select scope: `https://www.googleapis.com/auth/youtube`
   - Click **"Authorize APIs"** → Sign in with your Google account
   - Click **"Exchange authorization code for tokens"**
   - Copy the **Refresh Token**

The server automatically refreshes access tokens — you only need to set up credentials once.

### Important: Testing vs Production Mode

If your Google Cloud app is in **Testing** status, refresh tokens **expire every 7 days**. To get long-lived tokens:

1. Go to [OAuth consent screen](https://console.cloud.google.com/apis/credentials/consent) → Click **PUBLISH APP**
2. Confirm (no verification needed for personal use)
3. Get a new refresh token from OAuth Playground

| | Testing Mode | Production Mode |
|---|---|---|
| **Refresh Token** | Expires every 7 days | Never expires (until revoked) |
| **Who can use** | Test Users only (max 100) | Anyone |
| **Consent screen** | "Unverified app" warning | No warning (if verified) |

## Tools (20)

### Read Operations (10)

| Tool | Description | Quota |
|------|-------------|-------|
| `youtube_search` | Search videos, channels, playlists | 100 |
| `youtube_get_video` | Get video details by ID(s) | 1 |
| `youtube_get_channel` | Get channel info by ID or username | 1 |
| `youtube_list_playlists` | List playlists by channel or IDs | 1 |
| `youtube_list_playlist_items` | List videos in a playlist | 1 |
| `youtube_list_comments` | List top-level comments on video | 1 |
| `youtube_list_comment_replies` | List replies to a comment | 1 |
| `youtube_list_video_categories` | List available categories | 1 |
| `youtube_list_subscriptions` | List channel subscriptions | 1 |
| `youtube_get_popular_videos` | Get trending/popular videos | 1 |

### Write Operations (10)

| Tool | Description | Quota |
|------|-------------|-------|
| `youtube_post_comment` | Post top-level comment on video | 50 |
| `youtube_reply_comment` | Reply to existing comment | 50 |
| `youtube_update_comment` | Edit a comment | 50 |
| `youtube_delete_comment` | Delete a comment | 50 |
| `youtube_create_playlist` | Create a new playlist | 50 |
| `youtube_update_playlist` | Update playlist details | 50 |
| `youtube_delete_playlist` | Delete a playlist | 50 |
| `youtube_add_playlist_item` | Add video to playlist | 50 |
| `youtube_remove_playlist_item` | Remove video from playlist | 50 |
| `youtube_rate_video` | Like/dislike/unrate a video | 50 |

## Quota

YouTube Data API v3 has a daily quota of **10,000 units** per project.

| Operation | Cost |
|-----------|------|
| Search | 100 units |
| Read (list/get) | 1 unit |
| Write (create/update/delete) | 50 units |

Tips:
- Use `youtube_get_video` (1 unit) instead of `youtube_search` (100 units) when you have the video ID
- Use the `part` parameter to request only needed data

## Docker

```bash
docker compose up -d
# Endpoint: http://localhost:3000/mcp
```

## License

MIT License - see [LICENSE](LICENSE)

Copyright (c) 2026 [Node2Flow](https://node2flow.net)

## Links

- [npm Package](https://www.npmjs.com/package/@node2flow/youtube-mcp)
- [YouTube Data API v3 Documentation](https://developers.google.com/youtube/v3)
- [MCP Protocol](https://modelcontextprotocol.io/)
- [Node2Flow](https://node2flow.net)