# YouTube MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that gives AI coding agents full control over a YouTube channel. Works with Claude Code, Cursor, Windsurf, and any MCP-compatible client.

**22 tools** covering channel management, video operations, playlists, comments, search, analytics, thumbnails, and captions.

## What Can It Do?

| Category | Actions |
|----------|---------|
| **Channel** | Get channel info, update description/keywords/trailer |
| **Videos** | List, get details, upload from local file, update metadata, delete, set thumbnails |
| **Playlists** | List, create, update, delete, add/remove videos |
| **Comments** | List comment threads, reply to comments, delete comments |
| **Search** | Search YouTube for videos, channels, or playlists |
| **Analytics** | Channel analytics (views, watch time, subs, revenue), top videos |
| **Captions** | List available captions/subtitles |
| **Categories** | List assignable video categories by region |

## Quick Start

### 1. Get Google API Credentials

1. Go to the [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
2. Create a project (or select an existing one)
3. Enable the **YouTube Data API v3** and **YouTube Analytics API**
4. Create an **OAuth 2.0 Client ID** (type: Desktop app)
5. Note your **Client ID** and **Client Secret**

### 2. Install

```bash
git clone https://github.com/mrchevyceleb/youtube-mcp.git
cd youtube-mcp
npm install
npm run build
```

### 3. Set Environment Variables

```bash
export GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GOOGLE_CLIENT_SECRET="your-client-secret"
```

Or create a `.env` file (it is gitignored):

```
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
```

### 4. Authorize

```bash
npm run auth
```

This opens an interactive prompt:
1. It gives you a URL to open in your browser
2. Sign in with the Google account that owns your YouTube channel
3. Grant permissions
4. Copy the authorization code from the redirect URL
5. Paste it back into the terminal

Tokens are saved locally in `tokens.json` (gitignored). They auto-refresh, so you only need to do this once.

### 5. Add to Your MCP Client

#### Claude Code

Add to your Claude Code MCP config (`~/.claude.json` or project `.mcp.json`):

```json
{
  "mcpServers": {
    "youtube": {
      "command": "node",
      "args": ["/absolute/path/to/youtube-mcp/dist/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}
```

#### Cursor

Add to your Cursor MCP settings (`.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "youtube": {
      "command": "node",
      "args": ["/absolute/path/to/youtube-mcp/dist/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}
```

## Usage

Once connected, your AI agent gets a single `youtube` tool with an `action` parameter. Examples:

### Get your channel info
```
youtube({ action: "get_channel" })
```

### List your latest videos
```
youtube({ action: "list_videos", params: { maxResults: 10, orderBy: "date" } })
```

### Update a video's title and tags
```
youtube({
  action: "update_video",
  params: {
    videoId: "dQw4w9WgXcQ",
    title: "New Title",
    tags: ["tag1", "tag2", "tag3"]
  }
})
```

### Upload a video
```
youtube({
  action: "upload_video",
  params: {
    filePath: "/path/to/my-video.mp4",
    title: "How I Built This in 24 Hours",
    description: "Full walkthrough of building an app with AI coding agents.",
    tags: ["ai", "coding", "tutorial"],
    categoryId: "28",
    privacyStatus: "unlisted",
    playlistId: "PLxxxxxx"
  }
})
```

### Get analytics for the last 30 days
```
youtube({
  action: "get_analytics",
  params: {
    startDate: "2026-02-01",
    endDate: "2026-03-01",
    metrics: ["views", "estimatedMinutesWatched", "subscribersGained"]
  }
})
```

### Search YouTube
```
youtube({
  action: "search_youtube",
  params: { query: "vibe coding", type: "video", maxResults: 5 }
})
```

### Set a custom thumbnail
```
youtube({
  action: "set_thumbnail",
  params: {
    videoId: "dQw4w9WgXcQ",
    imageBase64: "<base64-encoded-image>",
    mimeType: "image/jpeg"
  }
})
```

## All 22 Actions

### Channel
- `get_channel` - Get channel info (name, stats, branding)
- `update_channel` - Update description, keywords, language, country, trailer

### Videos
- `list_videos` - List videos from a channel or playlist
- `get_video` - Get full video details (stats, tags, status)
- `upload_video` - Upload a video from a local file path (resumable, any size)
- `update_video` - Update title, description, tags, category, privacy
- `delete_video` - Permanently delete a video
- `set_thumbnail` - Upload a custom thumbnail (JPEG/PNG/BMP, max 2MB)

### Playlists
- `list_playlists` - List playlists from a channel
- `create_playlist` - Create a new playlist
- `update_playlist` - Update playlist title, description, privacy
- `add_to_playlist` - Add a video to a playlist
- `remove_from_playlist` - Remove a video from a playlist
- `delete_playlist` - Permanently delete a playlist

### Comments
- `list_comments` - List comment threads on a video
- `reply_to_comment` - Reply to a comment
- `delete_comment` - Delete a comment you own

### Search
- `search_youtube` - Search for videos, channels, or playlists

### Analytics
- `get_analytics` - Channel analytics (views, watch time, subs, revenue)
- `get_top_videos` - Top-performing videos by any metric

### Captions & Categories
- `list_captions` - List available captions/subtitles for a video
- `list_categories` - List assignable video categories by region

## How It Works

This server uses the [Model Context Protocol](https://modelcontextprotocol.io) to expose YouTube API operations as tools that AI agents can call. It communicates over stdio, which is the standard transport for local MCP servers.

Under the hood:
- **YouTube Data API v3** for channel, video, playlist, comment, and search operations
- **YouTube Analytics API v2** for analytics and top video queries
- **Google OAuth 2.0** with offline access for automatic token refresh
- **Zod** for input validation on every action
- **Router pattern** to expose all 21 actions as a single tool (reduces context token overhead)

## Requirements

- Node.js 20+
- A Google Cloud project with YouTube Data API v3 and YouTube Analytics API enabled
- OAuth 2.0 credentials (Desktop app type)

## License

MIT