YouTube MCP Server Technical Reference

Version: 1.0.0
Status: Production Ready
Location: /opt/mcp-servers/youtube/mcp_youtube_server.py
Ports: 6695 (vault), 6696 (operational)
Prefix: ytube
Category: YouTube System

Overview

The YouTube MCP Server is the central metadata hub for TubeForge, managing channels, episodes, and cross-environment linking. It follows the standard Nexus dual-Redis pattern (vault/operational) and integrates seamlessly with Gateway MCP via auto-discovery.

Total Tools: 11
Integration: Auto-discovered by Gateway
Redis: Standard vault/operational replication
Gateway Access: gateway.run([{server:'youtube', tool:'...', args:{...}}])

Architecture

Redis Environment

Vault Port: 6695 (password-protected, writes)
Operational Port: 6696 (read replica, no password)
Network: nexus-storage-network (Docker)
Prefix: ytube

Replication:

# Get vault IP
docker inspect nexus3-youtube-vault --format '{{range $key, $value := .NetworkSettings.Networks}}{{if eq $key "nexus-storage-network"}}{{$value.IPAddress}}{{end}}{{end}}'

# Configure operational
redis-cli -p 6696 CONFIG SET masterauth 'youtube_vault_password'
redis-cli -p 6696 REPLICAOF <vault_ip> 6379
redis-cli -p 6696 INFO replication | grep master_link_status
# Should show: master_link_status:up

Key Structure

Channels:

ytube:u_z1p5:channel:@chrisfoustdev
ytube:u_z1p5:channel:@corleraai

Episodes:

ytube:u_z1p5:episode:ep_xyz1
ytube:u_z1p5:episode:ep_abc2

Stable IDs: - Channels: ch_XXXX (4 alphanumeric) - Episodes: ep_XXXX (4 alphanumeric)

Data Models

Channel Structure:

channel_data = {
    "channel_id": "@chrisfoustdev",  # Handle or ch_XXXX
    "stable_id": "ch_4184",
    "name": "Chris Foust Dev",
    "description": "AI development tutorials",
    "episode_count": 12,
    "subscriber_count": 0,  # Future
    "created_at": "2026-01-11T12:00:00",
    "updated_at": "2026-01-11T14:30:00",
    "user": "u_z1p5"
}

Episode Structure:

episode_data = {
    "episode_id": "ep_xyz1",  # Stable ID
    "channel_id": "@chrisfoustdev",
    "title": "How to Build an MCP Server",
    "description": "Complete tutorial...",
    "hashtags": ["#MCP", "#AI", "#Development"],
    "keywords": ["MCP server", "Claude", "tutorial"],
    "status": "draft",  # draft|recording|editing|published

    # Cross-environment links
    "script_ids": ["c_abc1", "c_abc2", "c_abc3"],  # Corpus IDs
    "current_script_id": "c_abc3",
    "search_id": "web_srch_def2",  # Web environment
    "competitor_transcript_ids": ["t_xyz1", "t_xyz2"],  # Transcripts
    "cdn_script_path": "/data/cdn/users/chris/scripts/2026-01-11/ep_xyz1_v3.md",

    "created_at": "2026-01-11T10:00:00",
    "updated_at": "2026-01-11T14:45:00",
    "user": "u_z1p5"
}

Tool Reference

Channel Management (3 tools)

youtube.channel_create

Purpose: Create new YouTube channel

Parameters: - channel_id (required): Handle (e.g., @chrisfoustdev) or custom ID - name (required): Channel display name - description (optional): Channel description

Returns: Channel stable ID (ch_XXXX)

Example:

gateway.run([{
    server: 'youtube',
    tool: 'channel_create',
    args: {
        channel_id: '@chrisfoustdev',
        name: 'Chris Foust Dev',
        description: 'AI development tutorials and MCP servers'
    }
}])
# Returns: ch_4184

youtube.channel_list

Purpose: List all channels

Parameters: None

Returns: Array of channels with episode counts

Example:

gateway.run([{
    server: 'youtube',
    tool: 'channel_list',
    args: {}
}])

# Returns:
# [
#   {channel_id: '@chrisfoustdev', name: 'Chris Foust Dev', episode_count: 12},
#   {channel_id: '@corleraai', name: 'Corlera AI', episode_count: 5}
# ]

youtube.channel_get

Purpose: Get channel details

Parameters: - channel_id (required): Handle (@chrisfoustdev) or stable ID (ch_XXXX)

Returns: Full channel metadata

Example:

gateway.run([{
    server: 'youtube',
    tool: 'channel_get',
    args: {channel_id: '@chrisfoustdev'}
}])

# Returns full channel object with all fields

Episode Management (4 tools)

youtube.episode_create

Purpose: Create new episode

Parameters: - channel_id (required): Channel handle or stable ID - title (required): Episode title - description (optional): Episode description - hashtags (optional): Array of hashtags - keywords (optional): Array of keywords

Returns: Episode stable ID (ep_XXXX)

Example:

gateway.run([{
    server: 'youtube',
    tool: 'episode_create',
    args: {
        channel_id: '@chrisfoustdev',
        title: 'How to Build an MCP Server',
        description: 'Complete tutorial for MCP server development',
        hashtags: ['#MCP', '#AI', '#Tutorial'],
        keywords: ['MCP server', 'Claude', 'development']
    }
}])
# Returns: ep_xyz1

youtube.episode_update

Purpose: Update episode metadata

Parameters: - episode_id (required): Episode stable ID (ep_XXXX) - Any episode field to update (title, description, status, etc.)

Returns: Success confirmation

Example:

# Update status
gateway.run([{
    server: 'youtube',
    tool: 'episode_update',
    args: {
        episode_id: 'ep_xyz1',
        status: 'recording'
    }
}])

# Update multiple fields
gateway.run([{
    server: 'youtube',
    tool: 'episode_update',
    args: {
        episode_id: 'ep_xyz1',
        title: 'How to Build MCP Servers (Updated)',
        hashtags: ['#MCP', '#AI', '#Claude', '#Tutorial'],
        status: 'editing'
    }
}])

youtube.episode_get

Purpose: Get episode details

Parameters: - episode_id (required): Episode stable ID (ep_XXXX)

Returns: Full episode metadata

Example:

gateway.run([{
    server: 'youtube',
    tool: 'episode_get',
    args: {episode_id: 'ep_xyz1'}
}])

# Returns complete episode object with all linked IDs

youtube.episode_list

Purpose: List episodes for channel

Parameters: - channel_id (required): Channel handle or stable ID - status (optional): Filter by status (draft/recording/editing/published)

Returns: Array of episodes

Example:

# All episodes
gateway.run([{
    server: 'youtube',
    tool: 'episode_list',
    args: {channel_id: '@chrisfoustdev'}
}])

# Filter by status
gateway.run([{
    server: 'youtube',
    tool: 'episode_list',
    args: {
        channel_id: '@chrisfoustdev',
        status: 'draft'
    }
}])

Cross-Environment Linking (3 tools)

youtube.episode_link_script

Purpose: Link Corpus script to episode

Parameters: - episode_id (required): Episode stable ID - corpus_id (required): Corpus stable ID (c_XXXX)

Returns: Success confirmation

Effect: - Adds corpus_id to script_ids array - Sets as current_script_id

Example:

gateway.run([{
    server: 'youtube',
    tool: 'episode_link_script',
    args: {
        episode_id: 'ep_xyz1',
        corpus_id: 'c_abc3'
    }
}])

# Episode now has:
# script_ids: ['c_abc1', 'c_abc2', 'c_abc3']
# current_script_id: 'c_abc3'

youtube.episode_link_search

Purpose: Link Web search to episode

Parameters: - episode_id (required): Episode stable ID - search_id (required): Web search ID

Returns: Success confirmation

Effect: Sets search_id field

Example:

gateway.run([{
    server: 'youtube',
    tool: 'episode_link_search',
    args: {
        episode_id: 'ep_xyz1',
        search_id: 'web_srch_def2'
    }
}])

youtube.episode_link_transcript

Purpose: Link Transcript (competitor analysis) to episode

Parameters: - episode_id (required): Episode stable ID - transcript_id (required): Transcript ID from Transcripts environment

Returns: Success confirmation

Effect: Adds to competitor_transcript_ids array

Example:

# Link competitor transcript
gateway.run([{
    server: 'youtube',
    tool: 'episode_link_transcript',
    args: {
        episode_id: 'ep_xyz1',
        transcript_id: 't_xyz1'
    }
}])

# Episode now has:
# competitor_transcript_ids: ['t_xyz1', 't_xyz2', ...]

Aggregation (1 tool)

youtube.episode_full

Purpose: Get full episode context with all linked resources

Parameters: - episode_id (required): Episode stable ID

Returns: Episode metadata + all linked resource IDs

Use Case: Get complete picture before working on episode

Example:

gateway.run([{
    server: 'youtube',
    tool: 'episode_full',
    args: {episode_id: 'ep_xyz1'}
}])

# Returns:
# {
#   episode: {...full metadata...},
#   script_ids: ['c_abc1', 'c_abc2', 'c_abc3'],
#   current_script_id: 'c_abc3',
#   search_id: 'web_srch_def2',
#   competitor_transcript_ids: ['t_xyz1', 't_xyz2'],
#   cdn_script_path: '/data/cdn/users/chris/scripts/2026-01-11/ep_xyz1_v3.md'
# }

Integration Patterns

Pattern 1: Complete Workflow

End-to-end episode creation with all integrations:

# 1. Create episode
episode = gateway.run([{
    server: 'youtube',
    tool: 'episode_create',
    args: {
        channel_id: '@chrisfoustdev',
        title: 'How to Build an MCP Server',
        hashtags: ['#MCP', '#AI']
    }
}])
episode_id = episode[0]['text']  # Extract ep_XXXX

# 2. Search competitors (Web environment)
search = gateway.run([{
    server: 'web',
    tool: 'search',
    args: {query: 'how to build MCP server'}
}])
search_id = search[0]['id']

# 3. Get transcripts (Transcripts environment)
transcripts = gateway.run([
    {server: 'transcript', tool: 'youtube', args: {video_id: 'abc123'}},
    {server: 'transcript', tool: 'youtube', args: {video_id: 'def456'}}
])

# 4. Link everything
gateway.run([
    {server: 'youtube', tool: 'episode_link_search', args: {episode_id, search_id}},
    {server: 'youtube', tool: 'episode_link_transcript', args: {episode_id, transcript_id: transcripts[0]['id']}},
    {server: 'youtube', tool: 'episode_link_transcript', args: {episode_id, transcript_id: transcripts[1]['id']}}
])

# 5. Generate script (Corpus environment)
script = gateway.run([{
    server: 'corpus',
    tool: 'create',
    args: {
        category: 'youtube_script',
        title: 'MCP Tutorial - Script v1',
        content: '...script content...',
        tags: ['youtube', '@chrisfoustdev', episode_id]
    }
}])
script_id = script[0]['stable_id']

# 6. Link script
gateway.run([{
    server: 'youtube',
    tool: 'episode_link_script',
    args: {episode_id, corpus_id: script_id}
}])

# 7. Get full context
full = gateway.run([{
    server: 'youtube',
    tool: 'episode_full',
    args: {episode_id}
}])

Pattern 2: Batch Operations

Parallel tool calls for efficiency:

# Create multiple channels in parallel
gateway.run([
    {server: 'youtube', tool: 'channel_create', args: {channel_id: '@channel1', name: 'Channel 1'}},
    {server: 'youtube', tool: 'channel_create', args: {channel_id: '@channel2', name: 'Channel 2'}},
    {server: 'youtube', tool: 'channel_create', args: {channel_id: '@channel3', name: 'Channel 3'}}
])

# Get multiple episodes in parallel
gateway.run([
    {server: 'youtube', tool: 'episode_get', args: {episode_id: 'ep_xyz1'}},
    {server: 'youtube', tool: 'episode_get', args: {episode_id: 'ep_abc2'}},
    {server: 'youtube', tool: 'episode_get', args: {episode_id: 'ep_def3'}}
])

Pattern 3: Script Version Control

Using Corpus hierarchy for script versions:

# Create v1
v1 = corpus.create(
    category='youtube_script',
    title='MCP Tutorial - v1',
    content='...',
    tags=['youtube', episode_id]
)

# Link v1
youtube.episode_link_script(episode_id, v1.stable_id)

# Create v2 (links to v1 via parent_id)
v2 = corpus.create(
    category='youtube_script',
    title='MCP Tutorial - v2',
    content='...',
    parent_id=v1.id,  # Version control
    tags=['youtube', episode_id]
)

# Update to v2
youtube.episode_link_script(episode_id, v2.stable_id)

# Episode now has:
# script_ids: [v1.stable_id, v2.stable_id]
# current_script_id: v2.stable_id

Gateway Integration

Auto-Discovery

YouTube MCP auto-discovered by Gateway:

Gateway scans /opt/mcp-servers/
Finds /opt/mcp-servers/youtube/
Locates mcp_youtube_server.py
Parses tool definitions
Adds to available servers

No manual configuration required!

Verification

# Check YouTube is discovered
gateway.servers(refresh=True)

# Find YouTube tools
gateway.find('youtube channel')
gateway.find('episode')

# List all YouTube tools
gateway.servers(verbose=True)
# Shows all 11 tools

Performance

Discovery time: <2 seconds
Tool call latency: 50-150ms average
Batch execution: Parallel (up to 10 concurrent)
Cache TTL: 5 minutes (refreshable)

Testing

Integration Tests

All tests passed (100% success rate):

# Channel operations
gateway.run([{server:'youtube', tool:'channel_create', args:{...}}])  # ✓
gateway.run([{server:'youtube', tool:'channel_list', args:{}}])  # ✓
gateway.run([{server:'youtube', tool:'channel_get', args:{...}}])  # ✓

# Episode operations
gateway.run([{server:'youtube', tool:'episode_create', args:{...}}])  # ✓
gateway.run([{server:'youtube', tool:'episode_update', args:{...}}])  # ✓
gateway.run([{server:'youtube', tool:'episode_list', args:{...}}])  # ✓
gateway.run([{server:'youtube', tool:'episode_get', args:{...}}])  # ✓

# Linking
gateway.run([{server:'youtube', tool:'episode_link_script', args:{...}}])  # ✓
gateway.run([{server:'youtube', tool:'episode_link_search', args:{...}}])  # ✓
gateway.run([{server:'youtube', tool:'episode_link_transcript', args:{...}}])  # ✓

# Aggregation
gateway.run([{server:'youtube', tool:'episode_full', args:{...}}])  # ✓

Total Calls: 20+
Success Rate: 100%
Batch Execution: ✓ Working
Cross-Environment Linking: ✓ Validated

Known Issues

Issue: Replication lag when creating channel and episode in same batch

Root Cause: Redis replication from vault (6695) to operational (6696) has ~1-2 second lag

Workaround: Retry failed call OR add small delay between dependent operations

Future Fix: Update episode_create to verify channel from vault instead of operational

Redis Operations

Direct Access (Development/Debugging)

# Connect to operational (reads)
redis-cli -p 6696

# List all channels
KEYS ytube:u_z1p5:channel:*

# Get channel
GET ytube:u_z1p5:channel:@chrisfoustdev

# List all episodes
KEYS ytube:u_z1p5:episode:*

# Get episode
GET ytube:u_z1p5:episode:ep_xyz1

# Connect to vault (writes) - requires password
redis-cli -p 6695 -a youtube_vault_password

# Write channel (example - use MCP tools instead!)
SET ytube:u_z1p5:channel:@test '{...json...}'

# Check replication status
INFO replication

Backup/Migration

# Export all YouTube data
redis-cli -p 6696 --scan --pattern 'ytube:*' | xargs redis-cli -p 6696 DUMP > youtube_backup.rdb

# Restore to different environment
cat youtube_backup.rdb | redis-cli -p <target_port> --pipe

Production Deployment

Status: ✅ Production Ready

Checklist: - [x] MCP server deployed at /opt/mcp-servers/youtube/ - [x] Redis vault/operational configured (6695/6696) - [x] Gateway auto-discovery working - [x] All 11 tools tested and validated - [x] Cross-environment linking confirmed - [x] Batch execution verified - [x] Documentation complete - [ ] Monitoring/logging setup (future) - [ ] Analytics dashboard (future)

Future Enhancements

Planned Features

Analytics Integration
View counts per episode
Engagement metrics
Trending detection
Publishing Automation
YouTube API integration
Scheduled uploads
Thumbnail generation
Multi-Channel Dashboards
Cross-channel analytics
Performance comparisons
Content strategy insights
Advanced Linking
Track project integration
Contact tagging (collaborators)
Voice status announcements

Related KB Articles: - YouTube Content Creation System Overview - YouTube Discovery and Trending Analysis - YouTube Script Generation Complete Guide - YouTube Conversational Workflows

Server Location: /opt/mcp-servers/youtube/mcp_youtube_server.py
Redis Ports: 6695 (vault), 6696 (operational)
Gateway Access: Auto-discovered, all tools accessible