YouTube Researcher 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.

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.

Parameter	Type	Required	Default	Description
query	string	Yes	—	Search keyword(s)
maxResults	number	No	25	1–50
order	string	No	viewCount	viewCount, date, relevance, rating
publishedAfter	string	No	—	ISO 8601 date filter (e.g. 2025-01-01T00:00:00Z)
regionCode	string	No	—	ISO 3166-1 alpha-2 code (e.g. IE, GB, US)

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.

Parameter	Type	Required	Description
videoIds	string[]	Yes	Video IDs (max 50)

Returns per video:

Field	Type	Description
videoId	string	YouTube video ID
title	string	Video title
description	string	Full description text
tags	string[]	Video tags
publishedAt	string	ISO 8601 publish date
durationSeconds	number	Duration in seconds
durationFormatted	string	Human-readable duration (e.g. 12:34)
viewCount	number	Total views
likeCount	number	Total likes
commentCount	number	Total comments
channelId	string	Channel ID
channelTitle	string	Channel name
categoryId	string	YouTube category ID
thumbnailUrls	object	URLs at default/medium/high/standard/maxres sizes
engagementRate	number	(likes + comments) / views
likeToViewRatio	number	likes / views
commentDensity	number	comments / views
daysSincePublish	number	Days since publish (minimum 1)
viewVelocity	number	views / daysSincePublish

---

youtube_get_channel_details

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

Parameter	Type	Required	Description
channelIds	string[]	Yes	Channel IDs (max 50; duplicates removed)

Returns per channel:

Field	Type	Description
channelId	string	Channel ID
title	string	Channel name
description	string	Channel description
subscriberCount	number	Subscriber count
videoCount	number	Total videos published
totalViewCount	number	Lifetime view count
publishedAt	string	Channel creation date
thumbnailUrl	string	Channel avatar URL
hiddenSubscriberCount	boolean	Whether the sub count is hidden

---

youtube_analyse_niche

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

Parameter	Type	Required	Default	Description
query	string	Yes	—	Niche keyword(s)
maxResults	number	No	30	1–50. Recommend 10 for lean workflow
publishedAfter	string	No	—	ISO 8601 date filter
minViews	number	No	—	Minimum view count filter (post-fetch — see note)
order	string	No	viewCount	viewCount, date, relevance

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.

Parameter	Type	Required	Default	Description
videoIds	string[]	Yes	—	Video IDs (max 50)
outputDir	string	No	~/Downloads/youtube-thumbnails/YYYY-MM-DD/	Save path

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:

Metric	Formula
Engagement rate	(likes + comments) / views
Like-to-view ratio	likes / views
Comment density	comments / views
Days since publish	(now - publishedAt) / 86400000, minimum 1
View velocity	views / days since publish

Quota

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

Operation	Cost
Search (search.list)	100 units
Video details (videos.list, batch 50)	1 unit
Channel details (channels.list, batch 50)	1 unit
Thumbnail download	0 (direct fetch)

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