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
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
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)

npm install -g mcp-youtube-uploader

Option 2: Run with npx (No installation needed)

npx mcp-youtube-uploader

Option 3: Build from source

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):

{
  "mcpServers": {
    "youtube-uploader": {
      "command": "mcp-youtube-uploader"
    }
  }
}

With environment variables (recommended):

{
  "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:

{
  "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:

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

# Build the project
npm run build

# Watch for changes during development
npm run watch

# Test with MCP Inspector
npm run inspector