YouTube MCP

This project provides a Python MCP server for a practical YouTube upload and management workflow that uses the real YouTube Data API v3 and YouTube Analytics API with Google OAuth 2.0.

Architecture

The code is intentionally split into separate layers:

• youtube_mcp/server.py exposes MCP tools to Claude or any MCP client.
• youtube_mcp/services/youtube_service.py contains the actual YouTube API logic and validation.
• youtube_mcp/config.py reads environment variables and keeps secret values out of source control.

This separation keeps the tool layer focused on MCP contracts while the service layer handles YouTube API requests, validation, and error handling.

Required OAuth and API approach

This project is designed for authenticated workflow operations, not API-key-only use.

For upload, channel management, thumbnail update, and other private/channel-based actions, use Google OAuth 2.0 with the following scopes:

• https://www.googleapis.com/auth/youtube.upload
• https://www.googleapis.com/auth/youtube.readonly
• https://www.googleapis.com/auth/youtubepartner
• https://www.googleapis.com/auth/yt-analytics.readonly

The server expects these values in environment variables or a local .env file:

export GOOGLE_CLIENT_ID="your-google-client-id"
export GOOGLE_CLIENT_SECRET="your-google-client-secret"
export YOUTUBE_REFRESH_TOKEN="your-google-refresh-token"
export YOUTUBE_ACCESS_TOKEN="optional-current-access-token"
export YOUTUBE_CHANNEL_ID="optional-channel-id"

Never put client secrets, refresh tokens, or access tokens in source code or Git.

Tool set

hello_youtube

Simple validation tool that returns:

YouTube MCP is working

upload_video

Uploads a video file to YouTube.

Inputs:

• title (required)
• description (required)
• file_path (required local/publicly accessible path)
• tags (optional list of YouTube tag strings)
• hashtags (optional list of hashtags; these are added to the description text)
• privacy_status (optional: public, private, or unlisted)
• scheduled_publish_at (optional ISO 8601 future datetime; requires privacy_status="private" for YouTube scheduling)
• category_id (optional)
• made_for_kids (optional boolean)

Behavior:

• Does not fake a success result.
• Returns the uploaded video ID only when the YouTube API confirms it.
• Validates scheduled_publish_at and rejects non-future or invalid timestamps.
• Treats hashtags separately from YouTube tags; hashtags are represented in the title/description text, while tags go into the video tags field.

update_video

Updates video metadata.

Inputs:

• video_id (required)
• title (optional)
• description (optional)
• tags (optional)
• hashtags (optional)
• privacy_status (optional)
• scheduled_publish_at (optional)
• category_id (optional)
• made_for_kids (optional)

Rules:

• Requires a valid update payload.
• For scheduled publishing, YouTube requires private + publishAt workflow.
• Returns the API result only when the update request succeeds.

set_thumbnail

Sets a thumbnail image for an existing YouTube video.

Inputs:

• video_id (required)
• thumbnail_path (required local file path)

get_video_stats

Gets public YouTube video metadata and statistics for a given video ID.

get_channel_info

Fetches channel metadata for a channel ID, username, or mine=True when authenticated.

get_latest_videos

Lists recent videos for a channel.

get_video_analytics

Uses the YouTube Analytics API with authorized metrics for available reporting dimensions and filters.

Validation and error handling

The service layer validates:

• privacy_status
• scheduled_publish_at
• missing required parameters
• file existence for uploads and thumbnails
• OAuth environment configuration before channel or upload actions run

If the YouTube API responds with an error, the code raises a clear RuntimeError or ValueError with the API response details instead of masking the failure.

Local development / stdio mode

Run the local MCP server over stdio:

cd /workspaces/youtube-mcp
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -m youtube_mcp.server

This uses the local stdio transport for testing and debugging.

Remote HTTP MCP mode for Claude Custom Connector

The repository also supports a remote HTTP transport using the installed official MCP Python SDK.

Set the host/port and transport mode before starting the server:

cd /workspaces/youtube-mcp
source .venv/bin/activate
export YOUTUBE_MCP_TRANSPORT="http"
export YOUTUBE_MCP_HOST="127.0.0.1"
export YOUTUBE_MCP_PORT="8000"
export YOUTUBE_MCP_HTTP_PATH="/mcp"
python -m youtube_mcp.server

This exposes the MCP protocol at:

http://127.0.0.1:8000/mcp

The health endpoint is available at:

http://127.0.0.1:8000/health

You can verify the health endpoint with:

curl http://127.0.0.1:8000/health

Expected response:

{"status":"ok","service":"youtube-mcp","transport":"http"}

Notes

• .env is included in .gitignore.
• OAuth tokens and credentials are intentionally kept in environment variables.
• No fake API responses are used.
• No deployment or public publishing is configured in this repository.
• The Google OAuth redirect URI is not changed here.