YouTube Researcher MCP Server

v1.1.0 · MIT License

An MCP (Model Context Protocol) server for researching YouTube niches. Wraps the YouTube Data API v3 to search for videos, fetch metadata, calculate engagement metrics, download thumbnails, and produce aggregate niche statistics.

Built for Claude Code — define your niche, and the server returns structured data on what's working: title patterns, engagement rates, video lengths, top tags, channel sizes, and thumbnail images for visual analysis.

Recommended Workflow

For the leanest context usage, query 10 videos and delegate analysis to a subagent:

1. User provides topic — never assume or infer

2. youtube_analyse_niche(query, maxResults=10) — top 10 by view count with full metrics

3. youtube_get_thumbnails(videoIds) — download all 10 thumbnails

4. Spawn a single agent that reads the raw data + thumbnail images, analyses everything, and writes a research report to disk

5. Main context receives only the file path and a brief summary

This keeps the main conversation window clean. The analyse_niche tool returns large JSON (100KB+ at 30 videos) — always save to disk rather than processing in the primary context.

Companion Skill

A ready-made Claude Code skill is included in skill/SKILL.md. To install:

mkdir -p .claude/skills/researching-youtube-niche
cp skill/SKILL.md .claude/skills/researching-youtube-niche/SKILL.md

The skill handles the full workflow — topic prompt, niche analysis, thumbnail download, agent delegation, and report generation. Customise the output path and report structure to suit your workspace.

Related MCP server: YouTube MCP

Prerequisites

• Node.js >= 18

• A YouTube Data API v3 key (free tier — see setup below)

Google Cloud Setup

1. Go to Google Cloud Console

2. Create a new project (or select an existing one)

3. Navigate to APIs & Services > Library

4. Search for YouTube Data API v3 and click Enable

5. Navigate to APIs & Services > Credentials

6. Click Create Credentials > API Key

7. (Recommended) Restrict the key:

   • Click the key name to edit

   • Under API restrictions, select Restrict key and choose YouTube Data API v3

   • Under Application restrictions, optionally restrict by IP

8. Copy the API key

Installation

git clone https://github.com/larrygmaguire-hash/youtube-researcher-mcp.git
cd youtube-researcher-mcp
npm install

Pre-built JavaScript is included in build/ — no TypeScript compilation needed. To rebuild from source: npm run build.

Configuration

Environment Variable

Create a .env file or pass the key directly:

YOUTUBE_API_KEY=your_key_here

The server validates this at startup and exits if the key is missing.

Claude Code Registration

Global — add to ~/.claude.json:

{
  "mcpServers": {
    "youtube-researcher": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/youtube-researcher-mcp/build/index.js"],
      "env": {
        "YOUTUBE_API_KEY": "your_key_here"
      }
    }
  }
}

Workspace-scoped — add to .mcp.json in the workspace root (same structure). This keeps the server available only within that workspace.

Tools

youtube_search_niche

Search YouTube for videos by keyword. Returns video IDs sorted by view count, date, relevance, or rating.

Returns: { videoIds: string[], count: number, quotaUsed: number }

Note: This is the only tool that supports the rating sort order and the regionCode filter.

youtube_get_video_details

Fetch full metadata for video IDs. Returns title, description, tags, thumbnails, duration, view/like/comment counts, and calculated engagement metrics. Batches up to 50 per API call.

Returns per video:

youtube_get_channel_details

Fetch channel metadata including subscriber count, total views, and video count. Deduplicates channel IDs automatically.

Returns per channel:

youtube_analyse_niche

Primary entry point. Compound tool that searches, fetches video/channel details, calculates metrics, and returns aggregate statistics in a single call.

Automatic filters (no parameter needed):

• Videos under 60 seconds are excluded (Shorts detection by duration, not YouTube's Shorts flag)

• Active live streams are excluded

minViews gotcha: This is a post-fetch filter. The search and video detail API calls run first (consuming quota), then videos below the threshold are removed from results. A high minViews value can return very few or zero videos while still costing the full quota.

Not available on this tool: regionCode and rating sort order — use youtube_search_niche for those.

Returns:

{
  query: string,
  fetchedAt: string,              // ISO 8601 timestamp
  totalVideosAnalysed: number,
  videos: VideoMetrics[],         // Full per-video data (see youtube_get_video_details)
  channels: ChannelMetrics[],     // Deduplicated channel data
  aggregates: {
    medianViewCount: number,
    averageViewCount: number,
    medianEngagementRate: number,
    averageEngagementRate: number,
    medianDurationSeconds: number,
    medianLikeToViewRatio: number,
    topTags: [{ tag, count }],           // Top 20 by frequency
    durationDistribution: {              // Video count per bucket
      under5min, fiveToTen, tenToTwenty, overTwenty
    },
    publishDayDistribution: {            // Count by day of week (UTC)
      Monday, Tuesday, ...
    },
    channelSizeDistribution: {           // By subscriber count
      micro: <10K, mid: 10K-100K, large: 100K-1M, mega: 1M+
    }
  },
  quotaUsed: number
}

youtube_get_thumbnails

Download thumbnail images to a local directory. No API quota cost — fetches directly from YouTube's image CDN.

Behaviour: Tries maxresdefault.jpg first; falls back to hqdefault.jpg on 404. Files saved as [videoId].jpg.

Returns: { downloaded: number, outputDir: string, files: { [videoId]: "/absolute/path.jpg" } }

youtube_quota_status

Report estimated quota usage for the current server session. No parameters.

Returns:

{
  "quotaUsed": 103,
  "dailyLimit": 10000,
  "remaining": 9897,
  "note": "Quota resets at midnight Pacific Time. Usage is estimated..."
}

Note: The counter tracks usage within the current server process. It resets when the server restarts, and does not reflect the actual Google-side daily total.

Calculated Metrics

For each video, the server calculates:

Quota

YouTube Data API v3 provides 10,000 free units per day.

A typical full niche analysis: ~103 units. Daily budget allows ~48 analyses per day.

Quota resets at midnight Pacific Time.

Development

npm run dev    # Watch mode — recompiles on changes
npm run build  # One-time build
npm start      # Run the server

Tech stack: TypeScript 5.3, ES2022 target, NodeNext modules, @modelcontextprotocol/sdk ^1.0.0. No runtime dependencies beyond the MCP SDK — uses Node 18+ native fetch for all HTTP calls.

Licence

MIT