mcp-youtube

# YouTube Data MCP Server (@kirbah/mcp-youtube)

<!-- Badges Start -->
<p align="left">
  <!-- GitHub Actions CI -->
  <a href="https://github.com/kirbah/mcp-youtube/actions/workflows/ci.yml">
    <img src="https://github.com/kirbah/mcp-youtube/actions/workflows/ci.yml/badge.svg" alt="CI Status" />
  </a>
  <!-- Codecov -->
  <a href="https://codecov.io/gh/kirbah/mcp-youtube">
    <img src="https://codecov.io/gh/kirbah/mcp-youtube/branch/main/graph/badge.svg?token=Y6B2E0T82P" alt="Code Coverage"/>
  </a>
  <!-- NPM Version -->
  <a href="https://www.npmjs.com/package/@kirbah/mcp-youtube">
    <img src="https://img.shields.io/npm/v/@kirbah/mcp-youtube.svg" alt="NPM Version" />
  </a>
  <!-- NPM Downloads -->
  <a href="https://www.npmjs.com/package/@kirbah/mcp-youtube">
    <img src="https://img.shields.io/npm/dt/@kirbah/mcp-youtube.svg" alt="NPM Downloads" />
  </a>
  <!-- Node Version -->
  <a href="package.json">
    <img src="https://img.shields.io/node/v/@kirbah/mcp-youtube.svg" alt="Node.js Version Support" />
  </a>
</p>

<a href="https://glama.ai/mcp/servers/@kirbah/mcp-youtube">
  <img width="380" height="200" src="https://glama.ai/mcp/servers/@kirbah/mcp-youtube/badge" />
</a>
<!-- Badges End -->

**A production-grade YouTube Data MCP server engineered specifically for AI agents.**

Unlike standard API wrappers that flood your LLM with redundant data, this server strips away YouTube's heavy payload bloat. It is designed to save you massive amounts of context window tokens, protect your daily API quotas via caching, and run reliably without breaking your workflows.

## Why Choose This Server?

Most MCP servers are weekend projects. `@kirbah/mcp-youtube` is built for reliable, daily, cost-effective agentic workflows.

> 🎯 **Want feedback on your own channel, not just raw data?** Check out
> [CreatorLens](https://github.com/kirbah/CreatorLens) - a companion Claude
> Skill built on this MCP that diagnoses common growth problems (weak
> hooks, bad thumbnails, flatlined videos) using a real strategist's
> framework, not just numbers.

### 📉 1. Save Up to 87% on Tokens (and Context Window)

The raw YouTube API returns massive JSON payloads filled with nested eTags, redundant thumbnails, and localization data that LLMs don't need. This server structures the data to give your LLM exactly what it needs to reason, and nothing else.

```mermaid
%%{init: { "theme": "base", "themeVariables": { "xyChart": { "plotColorPalette": "#ef4444, #22c55e" } } } }%%
xychart-beta
    title "Token Consumption (Lower is Better)"
    x-axis ["getVideoDetails", "searchVideos", "getChannelStats"]
    y-axis "Context Tokens" 0 --> 1200
    bar "Raw YouTube API" [854, 1115, 673]
    bar "MCP-YouTube (Optimized)" [209, 402, 86]
```

| API Method             | Raw YouTube Tokens | MCP-YouTube Tokens | Token Savings | Data Size       |
| :--------------------- | :----------------- | :----------------- | :------------ | :-------------- |
| `getChannelStatistics` | 673                | **86**             | **~87% Less** | 1.9 KB ➔ 0.2 KB |
| `getVideoDetails`      | 854                | **209**            | **~75% Less** | 2.9 KB ➔ 0.6 KB |
| `searchVideos`         | 1115               | **402**            | **~64% Less** | 3.4 KB ➔ 1.2 KB |

_(Curious? You can compare the [raw API responses vs optimized outputs](examples/comparisons/) in the examples folder)._

### 🛡️ 2. Protect Your API Quotas (Smart Caching)

The YouTube Data API has strict daily limits (10,000 quota units). If your LLM gets stuck in a loop or re-asks a question, standard servers will drain your API limit in minutes.
This server includes an optional **MongoDB caching layer**. If your agent requests a video details or searches the same trending videos twice, the server serves it from the cache - costing you **0 API quota points**.

### 🏗️ 3. Production-Grade & Actively Maintained

Tired of MCP tools crashing your AI client? This server is built to be a rock-solid dependency:

- **97% Test Coverage:** Comprehensively unit-tested (check the Codecov badge).
- **Zero Lint Errors/Warnings:** Enforces strict, clean code (`npm run lint` passes 100%).
- **Active Security:** Automated Dependabot patching ensures underlying libraries are never left with known vulnerabilities.
- **Strict Type Safety:** Built using Zod validation and the robust MCP TypeScript Starter architecture.

---

## Quick Start: Installation

### 🟢 Zero-Config Mode (No API Key Required)

**Want to just fetch transcripts?** You can use this server immediately without any configuration! Just install and go. Add a YouTube API key later to unlock deep search and analytics.

The easiest way to install this server is by clicking the **"Add to Claude Desktop"** button on the [Glama server page](https://glama.ai/mcp/servers/@kirbah/mcp-youtube).

If you are configuring manually (e.g., in Cursor), just add this bare-minimum setup:

```json
{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "@kirbah/mcp-youtube"]
    }
  }
}
```

_✨ **Tip:** In Zero-Config mode, you can ask your AI to simply "Read the transcript for `youtube://transcript/{videoId}`"!_

### 🟡 Manual Configuration (Unlock All Features)

If you prefer to configure your MCP client manually (e.g., Claude Desktop or Cursor), add the following to your configuration file:

1. **Get a YouTube Data API v3 Key** (See [Setup Instructions](#youtube-api-setup) below).
2. **(Highly Recommended) Get a free MongoDB Connection String** to enable quota-saving caching.

```json
{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "@kirbah/mcp-youtube"],
      "env": {
        "YOUTUBE_API_KEY": "YOUR_YOUTUBE_API_KEY_HERE",
        "MDB_MCP_CONNECTION_STRING": "mongodb+srv://user:pass@cluster0.abc.mongodb.net/youtube_niche_analysis"
      }
    }
  }
}
```

_(Windows PowerShell Users: If `npx` fails, try using `"command": "cmd"` and `"args": ["/k", "npx", "-y", "@kirbah/mcp-youtube"]`)_

### Next Step: Add a Skill

Once your server is connected, try [CreatorLens](https://github.com/kirbah/CreatorLens) -
a Claude Skill built specifically for this MCP that turns raw YouTube data
into growth diagnostics (weak hooks, packaging, niche doubt, format pivots).

## Key Features

- **Optimized Video Information:** Search videos with advanced filters. Retrieve detailed metadata, statistics (views, likes, etc.), and content details, all structured for minimal token footprint.
- **Efficient Transcript Management:** Fetch video captions/subtitles with multi-language support, perfect for content analysis by LLMs.
- **Insightful Channel Analysis:** Get concise channel statistics (subscribers, views, video count) and discover a channel's top-performing videos without data bloat.
- **Lean Trend Discovery:** Find trending videos by region and category, and get lists of available video categories, optimized for quick AI processing.
- **Structured for AI:** All responses are designed to be easily parsable and immediately useful for language models.
- **Efficient Comment Retrieval:** Fetch video comments with fine-grained control over the number of results and replies, optimized for sentiment analysis and feedback extraction.

## Available Tools

The server provides the following MCP tools, each designed to return token-optimized data:

| Tool Name                       | Description                                                                                                                                  | Parameters (see details in tool schema)                                                                                                                   |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `getVideoDetails`               | Retrieves detailed, **lean** information for multiple YouTube videos including metadata, statistics, engagement ratios, and content details. | `videoIds` (array of strings)                                                                                                                             |
| `searchVideos`                  | Searches for videos or channels based on a query string with various filtering options, returning **concise** results.                       | `query` (string), `maxResults` (optional number), `order` (optional), `type` (optional), `channelId` (optional), etc.                                     |
| `getTranscripts`                | Retrieves **token-efficient** transcripts (captions) for multiple videos, with options for full text or key segments (intro/outro).          | `videoIds` (array of strings), `lang` (optional string for language code), `format` (optional enum: 'full_text', 'key_segments' - default 'key_segments') |
| `getChannelStatistics`          | Retrieves **lean** statistics for multiple channels (subscriber count, view count, video count, creation date).                              | `channelIds` (array of strings)                                                                                                                           |
| `getChannelTopVideos`           | Retrieves a list of a channel's top-performing videos with **lean** details and engagement ratios.                                           | `channelId` (string), `maxResults` (optional number)                                                                                                      |
| `getTrendingVideos`             | Retrieves a list of trending videos for a given region and optional category, with **lean** details and engagement ratios.                   | `regionCode` (optional string), `categoryId` (optional string), `maxResults` (optional number)