youtube-updater — YouTube Video Updater Agent

youtube-updater — YouTube Video Updater Agent

Optimises every product-related video on your channel for CTR, search rank, and LLM discoverability. Runs on demand. Sends full diff report to operator before any live write.

Never writes to YouTube without operator approval on title variants. Never keyword-stuffs. Never uses deceptive titles. YouTube ToS is a hard wall.

---

Required MCPs

Configure these in your Claude Desktop / Claude Code settings before running:

{
  "mcpServers": {
    "youtube-analytics": {
      "command": "npx",
      "args": ["youtube-channel-mcp"]
    }
  }
}

Optional MCPs (for full functionality):

• dfs-mcp — DataForSEO for real keyword volumes (never guess volumes without it)
• slack — send diff reports to a team channel before writing

Hosted option: Point at https://mcp.adityaarsharma.com/youtube-analytics/mcp with your bearer token instead of running locally.

---

Setup — Brand Config

Before running, fill in your brand details. The agent reads these instead of guessing:

Brand: [Your brand name]
Channel: [YouTube handle — @yourchannel]
Products:
  - [Product name] → [URL] → Docs: [docs URL]
  - [Product name] → [URL] → Docs: [docs URL]
Link fixes:
  - [old domain] → [new domain]   # dead domains, rebrands
  - Any Facebook Messenger links → [your contact page]
Contact page: [URL]
Slack channel for reports: [channel ID or "skip"]
Gemini API key: [YOUR_GEMINI_KEY]  # for timestamp generation

---

Phase 1 — Video Audit

Pull full channel video list:

mcp__youtube-analytics__get_all_videos

For each video:

1. Classify: product (mentions your brand/product by name or feature) vs general
2. For product videos only — pull 90-day analytics:

   mcp__youtube-analytics__get_analytics_over_time → impressions, CTR, views, watch_time
   mcp__youtube-analytics__get_video_details → current title, description, tags, chapters
   

3. Tag each video:
   • DECLINING — CTR or impressions dropped >20% vs prior 90 days
   • STALE — no update in 12+ months, links likely dead
   • HEALTHY — metrics stable, recent update → links-only fix
   • NEW — under 30 days old → skip

Priority order: DECLINING → STALE → HEALTHY

---

Phase 2 — Keyword Research (per video)

Pull real keyword data via DataForSEO. Never invent volumes.

mcp__dfs-mcp__dataforseo_labs_google_keyword_ideas
  seed: [video topic keywords, product name, feature name]
  location_code: 2840 (US)
  language_code: en

mcp__dfs-mcp__dataforseo_labs_google_keyword_suggestions
  seed: [current video title stripped of brand]

mcp__dfs-mcp__dataforseo_labs_search_intent
  keywords: [top candidates from above]

Filter — only use keywords that pass ALL three:

• Search volume ≥ 100/month
• Intent = informational OR commercial
• Not already in current title/description

Store per video: primary_kw (1 target), secondary_kws (2–4 supporting), intent

---

Phase 3 — Title Optimization

Generate exactly 3 title variants per product video.

Title rules (non-negotiable)

Must-have:

• Brand/product name in at least 2 of 3 variants
• primary_kw in at least 2 of 3 variants
• Under 70 characters
• Not a repeat of the current title

Banned patterns:

• "How to" as the only hook
• Listicles with fake numbers unless the video has that list
• ALL CAPS words
• Competitor brand in the title
• Questions that answer themselves
• Fake urgency ("Watch Before It's Too Late")

3-variant framework:

Variant	Angle	Formula
A	Keyword-exact + outcome	[primary_kw] — [specific result in numbers or time]
B	Emotion + curiosity gap	[surprising claim or challenge] + [product name]
C	Competitive/comparative	[product] vs [problem/alternative] — [what viewer gains]

---

Phase 4 — Description Update

Rule: patch and improve — do not rewrite the full description.

Step 4a — Link audit

For every URL in the description: check for 200 OK vs redirect vs 4xx/5xx. Apply your Link Fix map from brand config. For broken links (4xx/5xx): flag — do NOT auto-replace.

Step 4b — Keyword injection

• Add primary_kw naturally in first 150 characters (before "Show more" fold)
• Add 2–3 secondary_kws throughout body — one per paragraph
• Do not repeat the same keyword more than twice
• Never add keywords as a raw list — spam signal

Step 4c — Product links check

Description must contain at minimum:

• Product homepage URL
• Relevant docs/feature page URL (if video covers a specific feature)

If missing, add at the end:

— Links —
🔗 [Product Name]: [url]
📖 Docs: [docs url]

---

Phase 5 — Timestamps (Gemini)

API: https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=YOUR_GEMINI_KEY

Case A — No timestamps in description

Generate keyword-rich timestamps from scratch:

VIDEO_URL="https://www.youtube.com/watch?v={VIDEO_ID}"
GEMINI_KEY="YOUR_GEMINI_KEY"
PRODUCT_CONTEXT="[product name and topic]"
SECONDARY_KWS="[comma-separated secondary keywords]"

curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GEMINI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [
        {"text": "Watch this YouTube video and generate SEO-optimised timestamps. Rules: (1) Chapter titles must target search keywords — Google indexes these. (2) LLMs also parse chapters for topic signals. (3) Format: MM:SS Chapter Title. (4) 6-12 chapters max. (5) First chapter must be 0:00. (6) Titles should match how someone would search for that sub-topic. Product context: '"${PRODUCT_CONTEXT}"'. Target keywords: '"${SECONDARY_KWS}"'. Return only the timestamp list, no explanation."},
        {"file_data": {"mime_type": "video/*", "file_uri": "'"$VIDEO_URL"'"}}
      ]
    }]
  }'

Case B — Timestamps already exist

Do NOT reread the transcript. Do NOT change timing values.

Parse existing timestamps: \d{1,2}:\d{2}[^\n]*

Send labels only to Gemini for keyword improvement, then recombine with original timecodes.

Timestamp format in description

⏱ Chapters
0:00 Introduction
1:23 [keyword-rich label]
...

---

Phase 6 — Research Guard (YouTube ToS)

Automatic FAIL — do not include:

• Title makes a claim not in the video
• Keyword count in description >3% of total word count
• Competitor brand name in title
• Fake timestamps that don't match video content
• "Subscribe" or "Like" in the first 30 characters of description

Flag for operator (don't auto-fail):

• Emotional title variant that could read as clickbait → [FLAG: verify matches video tone]
• Videos older than 2 years → [FLAG: verify content still accurate]

---

Phase 7 — Output Report

Send full diff report to operator before any YouTube write.

📹 VIDEO UPDATE REPORT
──────────────────────
Video: [title] | [URL]
Status: [DECLINING / STALE / HEALTHY]

📊 METRICS (last 90 days)
  Impressions: X → Y (▼Z%)
  CTR: X% → Y%

🔤 TITLE OPTIONS (pick one, or revise)
  Current: [existing title]
  A — [Keyword-exact variant]
  B — [Emotion/curiosity variant]
  C — [Competitive/comparative variant]
  Primary keyword: [kw] | Vol: [n/mo]

🔗 LINKS CHANGED
  ✅ [old] → [new]
  🚩 FLAGGED: [broken URL]

🔑 KEYWORDS ADDED
  + [keyword 1] (opening para)
  + [keyword 2] (body)

⏱ TIMESTAMPS
  [Added / Updated labels / Skipped]

⚠️ FLAGS
  [Research Guard flags, or "None"]

────
Reply: approve [A/B/C] | revise: [feedback] | skip

---

Phase 8 — Pinned Keyword Comment (post-approval)

After operator approves and changes go live:

Step 1 — Check if one already exists:

mcp__youtube-analytics__get_video_comments
  video_id: {VIDEO_ID}
  maxResults: 5

If first result is from channel owner and has a timestamp → skip.

Step 2 — Draft the comment:

• One timestamp from the most valuable chapter
• Primary keyword in natural phrasing
• End with one question (drives replies = engagement signal)
• Under 300 chars, no ALL CAPS

Jump to {MM:SS} to see {keyword-rich description}.

{One question to the viewer}

Step 3 — Post:

mcp__youtube-analytics__post_video_comment
  video_id: {VIDEO_ID}
  comment_text: {drafted comment}

Step 4 — Pin it: Tool returns studio_pin_url — open it → find comment → ⋮ → Pin (10 seconds).

YouTube Data API v3 has no pin endpoint — pinning is Studio-only. The tool posts and gives you the direct URL.

---

Hard Rules

1. Never write to YouTube before operator approves title choice.
2. Never invent keyword volumes — DataForSEO only.
3. Never use Gemini to reread transcript on videos that already have timestamps.
4. Never replace a broken link with a guess — flag it.
5. Never add competitor brand names to titles.
6. All Facebook / Messenger links → your contact page.
7. Broken link = flag, not auto-fix.