🎯 YouTube Intelligence MCP

A powerful, self-hosted vidIQ alternative & YouTube channel command center for AI Agents.
Zero-quota competitor scraping, mathematical outlier detection, on-screen video vision OCR, international content arbitrage, and private channel analytics via OAuth2.

⚡ Why This Exists (The Problem with Traditional Tools)

Traditional YouTube intelligence platforms (like vidIQ or TubeBuddy) charge $40 to $100+/month, lock your historical data behind walled gardens, and give generic AI suggestions.

On the engineering side, building on the official Google YouTube Data API v3 carries a critical trap: the 10,000 units/day quota limit (a single search consumes 100 units, hitting rate-limits in minutes).

YouTube Intelligence MCP solves this with a Hybrid Engine Architecture:

1. Competitor & Market Intelligence (Zero Quota): Fast flat-playlist scraping via yt-dlp extracts views, engagement, and metadata without spending a single Google API quota unit.

2. True Outlier Math: Uses sample-median baseline calculation ($Multiplier = \frac{Views}{Median(Views_{last20})}$) to separate genuine breakout videos ($2.5\times$ to $25\times$) from channel subscriber momentum.

3. AI Video Vision & OCR: Extracts keyframes with FFmpeg and reads on-screen code, terminal commands, slides, and editor tabs using local Tesseract OCR.

4. International Content Arbitrage: Automatically discovers foreign breakout videos in your niche (e.g. US/EU creators with 20k subs getting 1M views) and adapts titles/hooks for the local market.

5. Private Channel Audit (via Google OAuth): Securely connects your channels to pull watch time, average retention %, CTR, and traffic source distribution (Search vs Browse/Suggested).

Related MCP server: riocloud-reader

🏗️ Architecture

graph TD
    AI[AI Agent: Hermes / Claude / Codex / Cursor] -->|MCP Protocol / stdio| SERVER[FastMCP Server: yt-intelligence]
    
    subgraph Market Intelligence [Zero API Quota Engine]
        SERVER -->|Scrapes Flat Playlists| COMP[Competitor Engine: yt-dlp]
        SERVER -->|Calculates Outlier Scores| OUTLIER[Outlier Math Engine: Medians & Multipliers]
        SERVER -->|Discovers Viral Gringo Outliers| ARBITRAGE[International Content Arbitrage]
        SERVER -->|Extracts Frames + OCR| VISION[Video Vision: FFmpeg + Tesseract]
        SERVER -->|Niche Gaps & Durations| RADAR[Niche Radar Engine]
    end

    subgraph Owned Channels [Authenticated Engine]
        SERVER -->|OAuth2 Refresh Tokens| AUTH[Headless OAuth Manager]
        AUTH -->|Private Metrics & Retention| YT_ANALYTICS[YouTube Analytics API v2]
        AUTH -->|Video Details & Top Comments| YT_DATA[YouTube Data API v3]
    end

🛠️ MCP Tools Catalog

This server exposes 9 comprehensive tools ready for any MCP-compliant client:

🚀 Quickstart

1. Installation

# Clone the repository
git clone https://github.com/LucasOliveira09/yt-intelligence-mcp.git
cd yt-intelligence-mcp

# Create virtual environment and install dependencies
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. Standalone CLI Usage

The repository includes a rich terminal CLI for quick research without launching an agent:

# 1. Analyze any competitor channel for outliers (Zero Quota)
python -m src.cli analyze @BeroODev --limit 20

# 2. Mine international viral content opportunities (Content Arbitrage)
python -m src.cli arbitrage "GTA 6" --views 50000

# 3. Flexible search with filters (e.g., videos posted today, sorted by views)
python -m src.cli search "AI agents" --period this_week --sort view_count --limit 10

# 4. Connect your own YouTube channel via Google OAuth
python -m src.cli add-account my_channel

🤖 MCP Client Setup

A. Hermes Agent (~/.hermes/config.yaml)

mcp_servers:
  yt-intelligence:
    command: /path/to/yt-intelligence-mcp/run_server.sh
    enabled: true

B. Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "yt-intelligence": {
      "command": "/path/to/yt-intelligence-mcp/.venv/bin/python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/yt-intelligence-mcp"
    }
  }
}

C. Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "yt-intelligence": {
      "command": "/path/to/yt-intelligence-mcp/run_server.sh"
    }
  }
}

🔐 Security & Privacy Posture

• Zero Credential Leaks: Refresh tokens and OAuth credentials are saved strictly to data/accounts.json with chmod 600 permissions and are permanently ignored in .gitignore.

• Safe VPS Execution: Temporary video streams downloaded for frame extraction are deleted immediately after keyframe capture to prevent disk consumption.

• Local First: Runs 100% on your own hardware or VPS over stdio without third-party telemetry.

📄 License

Distributed under the MIT License. Built by Lucas Leite de Oliveira.