mcp-youtube-uploader/README.md

MCP server for uploading videos to YouTube with OAuth2 authentication

# YouTube MCP Uploader

A Model Context Protocol (MCP) server that enables uploading videos to YouTube and retrieving uploaded video URLs.

## Features

- **OAuth2 Authentication**: Secure authentication with YouTube/Google APIs
- **Video Upload**: Upload videos with metadata (title, description, tags, privacy)
- **URL Retrieval**: Returns YouTube video URLs after successful upload
- **Error Handling**: Comprehensive error handling and validation

## Prerequisites

1. **Google Cloud Project**: Create a project in [Google Cloud Console](https://console.cloud.google.com/)
2. **YouTube Data API**: Enable the YouTube Data API v3 for your project
3. **OAuth2 Credentials**: Create OAuth2 client credentials (Web application or Desktop application)

**Required OAuth2 Scopes:**
- `https://www.googleapis.com/auth/youtube` - Full YouTube API access
- `https://www.googleapis.com/auth/youtube.force-ssl` - HTTPS access for all operations

These broad scopes ensure access to all channels you own or have manager permissions for.

### Setting up Google OAuth2 Credentials

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Select your project or create a new one
3. Navigate to "APIs & Services" > "Library"
4. Search for "YouTube Data API v3" and enable it
5. Go to "APIs & Services" > "Credentials"
6. Click "Create Credentials" > "OAuth 2.0 Client IDs"
7. Choose "Desktop application" or "Web application" 
8. Set redirect URI (e.g., `http://localhost:8080/oauth2callback` for desktop apps)
9. Download the credentials JSON file

## Installation

### Option 1: Install from npm (Recommended)
```bash
npm install -g mcp-youtube-uploader
```

### Option 2: Run with npx (No installation needed)
```bash
npx mcp-youtube-uploader
```

### Option 3: Build from source
```bash
git clone https://github.com/yourusername/mcp-youtube-uploader.git
cd mcp-youtube-uploader
npm install
npm run build
```

## Usage

### Tools Available

#### 1. `get_auth_url`
Get OAuth2 authorization URL for YouTube authentication.

**Parameters:**
- `clientId` (string, optional): Your Google OAuth2 client ID (optional if `YOUTUBE_CLIENT_ID` env var is set)
- `clientSecret` (string, optional): Your Google OAuth2 client secret (optional if `YOUTUBE_CLIENT_SECRET` env var is set)
- `redirectUri` (string, optional): OAuth2 redirect URI (optional if `YOUTUBE_REDIRECT_URI` env var is set)

#### 2. `set_auth_code`
Complete authentication by providing the authorization code from OAuth2 flow.

**Parameters:**
- `authCode` (string): Authorization code received from OAuth2 redirect

#### 3. `set_refresh_token`
Authenticate using a saved refresh token (skip OAuth2 flow for repeat sessions).

**Parameters:**
- `clientId` (string, optional): Your Google OAuth2 client ID (optional if `YOUTUBE_CLIENT_ID` env var is set)
- `clientSecret` (string, optional): Your Google OAuth2 client secret (optional if `YOUTUBE_CLIENT_SECRET` env var is set)
- `redirectUri` (string, optional): OAuth2 redirect URI (optional if `YOUTUBE_REDIRECT_URI` env var is set)
- `refreshToken` (string): Refresh token from previous authentication

#### 4. `list_channels`
List all YouTube channels the authenticated user can manage.

**Parameters:** None

**Returns:** List of available channels with IDs, names, subscriber counts, and descriptions.

#### 5. `debug_permissions`
Debug tool to troubleshoot channel access and permissions.

**Parameters:** None

**Returns:** Detailed information about API permissions, scopes, and accessible resources.

#### 6. `upload_video`
Upload a video to YouTube and get the video URL.

**Parameters:**
- `filePath` (string): Path to the video file to upload
- `title` (string): Title of the video
- `description` (string, optional): Description of the video
- `tags` (array, optional): Tags for the video
- `categoryId` (string, optional): YouTube category ID (default: 22 - People & Blogs)
- `privacyStatus` (string, optional): Privacy status - 'private', 'public', or 'unlisted' (default: 'private')
- `channelId` (string, optional): YouTube channel ID to upload to (use `list_channels` to see available options)

### Authentication Flow

**Option 1: First Time (OAuth2 Flow)**
1. Use `get_auth_url` with your OAuth2 credentials
2. Visit the returned URL in your browser
3. Authorize the application and copy the authorization code
4. Use `set_auth_code` with the authorization code
5. Save the returned refresh token for future use
6. You can now use `upload_video` to upload videos

**Option 2: Subsequent Sessions (Refresh Token)**
1. Use `set_refresh_token` with your credentials and saved refresh token
2. You can immediately use `upload_video` to upload videos

### Multi-Channel Management

If you manage multiple YouTube channels (personal + brand accounts, or multiple brand accounts):

1. **Authenticate** using any of the methods above
2. **List channels** with `list_channels` to see all available channels
3. **Upload to specific channel** by including `channelId` parameter in `upload_video`

**Example workflow:**
```
1. authenticate → 2. list_channels → 3. upload_video with channelId
```

### Example MCP Client Configuration

Add this to your Claude Desktop configuration:

**Basic configuration (installed globally):**
```json
{
  "mcpServers": {
    "youtube-uploader": {
      "command": "mcp-youtube-uploader"
    }
  }
}
```

**With environment variables (recommended):**
```json
{
  "mcpServers": {
    "youtube-uploader": {
      "command": "mcp-youtube-uploader",
      "env": {
        "YOUTUBE_CLIENT_ID": "your_google_oauth_client_id",
        "YOUTUBE_CLIENT_SECRET": "your_google_oauth_client_secret",
        "YOUTUBE_REDIRECT_URI": "http://localhost:3000/callback"
      }
    }
  }
}
```

**If using npx:**
```json
{
  "mcpServers": {
    "youtube-uploader": {
      "command": "npx",
      "args": ["mcp-youtube-uploader"],
      "env": {
        "YOUTUBE_CLIENT_ID": "your_google_oauth_client_id",
        "YOUTUBE_CLIENT_SECRET": "your_google_oauth_client_secret",
        "YOUTUBE_REDIRECT_URI": "http://localhost:3000/callback"
      }
    }
  }
}
```

**If built from source:**
```json
{
  "mcpServers": {
    "youtube-uploader": {
      "command": "/path/to/mcp-youtube-uploader/build/index.js",
      "env": {
        "YOUTUBE_CLIENT_ID": "your_google_oauth_client_id",
        "YOUTUBE_CLIENT_SECRET": "your_google_oauth_client_secret",
        "YOUTUBE_REDIRECT_URI": "http://localhost:3000/callback"
      }
    }
  }
}
```

### Environment Variables

You can configure OAuth2 credentials using environment variables instead of passing them as parameters:

- `YOUTUBE_CLIENT_ID` - Your Google OAuth2 client ID
- `YOUTUBE_CLIENT_SECRET` - Your Google OAuth2 client secret
- `YOUTUBE_REDIRECT_URI` - OAuth2 redirect URI

When environment variables are set, the `clientId`, `clientSecret`, and `redirectUri` parameters become optional for `get_auth_url` and `set_refresh_token` tools.

## Limitations

- **Upload Quota**: YouTube allows maximum 50 video uploads per day per account
- **File Size**: Maximum file size is 128GB (YouTube's limit)
- **Authentication**: Requires OAuth2 flow for each new session (unless refresh token is saved)
- **API Quota**: Subject to YouTube Data API quota limits

## File Structure

```
mcp-youtube-uploader/
├── src/
│   ├── index.ts              # Main MCP server
│   ├── youtube-client.ts     # YouTube API client
│   └── types.ts              # TypeScript interfaces
├── build/                    # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md
```

## Error Handling

The server handles various error scenarios:
- Invalid file paths or missing files
- YouTube API errors (quota exceeded, invalid parameters)
- Authentication failures
- File size limits
- Network connectivity issues

## Security Notes

- Never commit your OAuth2 credentials to version control
- Store credentials securely (environment variables, secure credential store)
- Use appropriate redirect URIs for your environment
- Consider implementing refresh token persistence for production use

## Development

```bash
# Build the project
npm run build

# Watch for changes during development
npm run watch

# Test with MCP Inspector
npm run inspector
```