[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_111":112},"routes/modules.$creator.$moduleId",{"_14":15,"_16":17,"_18":19,"_20":21},"routes/modules.$creator.$moduleId.endpoints",{"_11":12,"_13":-5},"error","Module not found","tools","module",{"_20":22,"_23":24,"_25":26,"_27":28,"_29":30,"_31":32,"_33":34,"_35":26,"_36":37,"_38":-5,"_39":-5,"_40":41,"_42":43,"_44":45,"_46":47,"_48":49,"_50":51,"_52":53,"_54":55,"_56":-5,"_57":49,"_58":59,"_60":61,"_62":-5,"_63":-5,"_64":11,"_65":49,"_66":67,"_68":69,"_70":71,"_72":73,"_74":75,"_76":-5,"_77":-5,"_78":-5,"_79":49,"_80":-5,"_81":82,"_83":84,"_85":86,"_87":88,"_89":90,"_91":92,"_93":94},"apiUrl","https://odel.app/api","creator","kirbah","moduleId","mcp-youtube","@kirbah/mcp-youtube","displayName","mcp youtube","tagline","Provide token-optimized, structured YouTube data to enhance your LLM applications. Access efficien…","iconKey","https://avatars.githubusercontent.com/u/3257689?v=4","category","remote","status","published","visibility","public","metaDescription","deploymentType","external","workerName","bindingName","mcpConfig","{\"url\":\"https://server.smithery.ai/@kirbah/mcp-youtube/mcp\",\"transport\":\"streamable-http\",\"authType\":\"bearer\"}","pricingModel","free","creatorUserId","system:external-import","createdAt",1781363218000,"updatedAt",1788755190000,"sourceRegistry","official-mcp-registry","sourceUrl","https://registry.modelcontextprotocol.io/v0/servers?search=ai.smithery%2Fkirbah-mcp-youtube","sourceVerified",false,"sourceMissingSince","importedAt","upstreamStars",29,"upstreamUpdatedAt",1788406604000,"detectedTransport","detectedAuthType","probeStatus","lastProbedAt","githubRepoUrl","https://github.com/kirbah/mcp-youtube","githubRepoFullName","kirbah/mcp-youtube","releaseId","ext-kirbah-mcp-youtube","version","0.2.6","descriptionMarkdown","# YouTube Data MCP Server (@kirbah/mcp-youtube)\n\n[![MCP Toplist](https://mcptoplist.com/badge/io.github.kirbah%2Fmcp-youtube.svg)](https://mcptoplist.com/server/io.github.kirbah%2Fmcp-youtube)\n\n\n

\n \n \n $\"CI$ \n \n \n \n $\"Code$ \n \n \n \n $\"NPM$ \n \n \n \n $\"NPM$ \n \n \n \n $\"Node.js$ \n \n

\n\n\n

\n\n\n\n**A production-grade YouTube Data MCP server engineered specifically for AI agents.**\n\nUnlike 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.\n\n## Why Choose This Server?\n\nMost MCP servers are weekend projects. `@kirbah/mcp-youtube` is built for reliable, daily, cost-effective agentic workflows.\n\n> 🎯 **Want feedback on your own channel, not just raw data?** Check out\n> [CreatorLens](https://github.com/kirbah/CreatorLens) - a companion Claude\n> Skill built on this MCP that diagnoses common growth problems (weak\n> hooks, bad thumbnails, flatlined videos) using a real strategist's\n> framework, not just numbers.\n\n### 📉 1. Save Up to 87% on Tokens (and Context Window)\n\nThe 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.\n\n```mermaid\n%%{init: { \"theme\": \"base\", \"themeVariables\": { \"xyChart\": { \"plotColorPalette\": \"#ef4444, #22c55e\" } } } }%%\nxychart-beta\n title \"Token Consumption (Lower is Better)\"\n x-axis [\"getVideoDetails\", \"searchVideos\", \"getChannelStats\"]\n y-axis \"Context Tokens\" 0 --> 1200\n bar \"Raw YouTube API\" [854, 1115, 673]\n bar \"MCP-YouTube (Optimized)\" [209, 402, 86]\n```\n\n| API Method | Raw YouTube Tokens | MCP-YouTube Tokens | Token Savings | Data Size |\n| :--------------------- | :----------------- | :----------------- | :------------ | :-------------- |\n| `getChannelStatistics` | 673 | **86** | **~87% Less** | 1.9 KB ➔ 0.2 KB |\n| `getVideoDetails` | 854 | **209** | **~75% Less** | 2.9 KB ➔ 0.6 KB |\n| `searchVideos` | 1115 | **402** | **~64% Less** | 3.4 KB ➔ 1.2 KB |\n\n_(Curious? You can compare the [raw API responses vs optimized outputs](https://github.com/kirbah/mcp-youtube/blob/main/examples/comparisons/) in the examples folder)._\n\n### 🛡️ 2. Protect Your API Quotas (Smart Caching)\n\nThe 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.\nThis 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**.\n\n### 🏗️ 3. Production-Grade & Actively Maintained\n\nTired of MCP tools crashing your AI client? This server is built to be a rock-solid dependency:\n\n- **97% Test Coverage:** Comprehensively unit-tested (check the Codecov badge).\n- **Zero Lint Errors/Warnings:** Enforces strict, clean code (`npm run lint` passes 100%).\n- **Active Security:** Automated Dependabot patching ensures underlying libraries are never left with known vulnerabilities.\n- **Strict Type Safety:** Built using Zod validation and the robust MCP TypeScript Starter architecture.\n\n---\n\n## Quick Start: Installation\n\n### 🟢 Zero-Config Mode (No API Key Required)\n\n**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.\n\nThe 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).\n\nIf you are configuring manually (e.g., in Cursor), just add this bare-minimum setup:\n\n```json\n{\n \"mcpServers\": {\n \"youtube\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@kirbah/mcp-youtube\"]\n }\n }\n}\n```\n\n_✨ **Tip:** In Zero-Config mode, you can ask your AI to simply \"Read the transcript for `youtube://transcript/{videoId}`\"!_\n\n### 🟡 Manual Configuration (Unlock All Features)\n\nIf you prefer to configure your MCP client manually (e.g., Claude Desktop or Cursor), add the following to your configuration file:\n\n1. **Get a YouTube Data API v3 Key** (See [Setup Instructions](#youtube-api-setup) below).\n2. **(Highly Recommended) Get a free MongoDB Connection String** to enable quota-saving caching.\n\n```json\n{\n \"mcpServers\": {\n \"youtube\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@kirbah/mcp-youtube\"],\n \"env\": {\n \"YOUTUBE_API_KEY\": \"YOUR_YOUTUBE_API_KEY_HERE\",\n \"MDB_MCP_CONNECTION_STRING\": \"mongodb+srv://user:pass@cluster0.abc.mongodb.net/youtube_niche_analysis\"\n }\n }\n }\n}\n```\n\n_(Windows PowerShell Users: If `npx` fails, try using `\"command\": \"cmd\"` and `\"args\": [\"/k\", \"npx\", \"-y\", \"@kirbah/mcp-youtube\"]`)_\n\n### Next Step: Add a Skill\n\nOnce your server is connected, try [CreatorLens](https://github.com/kirbah/CreatorLens) -\na Claude Skill built specifically for this MCP that turns raw YouTube data\ninto growth diagnostics (weak hooks, packaging, niche doubt, format pivots).\n\n## Key Features\n\n- **Optimized Video Information:** Search videos with advanced filters. Retrieve detailed metadata, statistics (views, likes, etc.), and content details, all structured for minimal token footprint.\n- **Efficient Transcript Management:** Fetch video captions/subtitles with multi-language support, perfect for content analysis by LLMs.\n- **Insightful Channel Analysis:** Get concise channel statistics (subscribers, views, video count) and discover a channel's top-performing videos without data bloat.\n- **Lean Trend Discovery:** Find trending videos by region and category, and get lists of available video categories, optimized for quick AI processing.\n- **Structured for AI:** All responses are designed to be easily parsable and immediately useful for language models.\n- **Efficient Comment Retrieval:** Fetch video comments with fine-grained control over the number of results and replies, optimized for sentiment analysis and feedback extraction.\n\n## Available Tools\n\nThe server provides the following MCP tools, each designed to return token-optimized data:\n\n| Tool Name | Description | Parameters (see details in tool schema) |\n| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `getVideoDetails` | Retrieves detailed, **lean** information for multiple YouTube videos including metadata, statistics, engagement ratios, and content details. | `videoIds` (array of strings) |\n| `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. |\n| `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') |\n| `getChannelStatistics` | Retrieves **lean** statistics for multiple channels (subscriber count, view count, video count, creation date). | `channelIds` (array of strings) |\n| `getChannelTopVideos` | Retrieves a list of a channel's top-performing videos with **lean** details and engagement ratios. | `channelId` (string), `maxResults` (optional number) |\n| `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) |\n| `getVideoCategories` | Retrieves available YouTube video categories (ID and title) for a specific region, providing **essential data only**. | `regionCode` (optional string) |\n| `getVideoComments` | Retrieves comments for a YouTube video. Allows sorting, limiting results, and fetching a small number of replies per comment. | `videoId` (string), `maxResults` (optional number), `order` (optional), `maxReplies` (optional number), `commentDetail` (optional string) |\n| `findConsistentOutlierChannels` | Identifies channels that consistently perform as outliers within a specific niche. **Requires a MongoDB connection.** | `niche` (string), `minVideos` (optional number), `maxChannels` (optional number) |\n\n_For detailed input parameters and their descriptions, please refer to the `inputSchema` within each tool's configuration file in the `src/tools/` directory (e.g., `src/tools/video/getVideoDetails.ts`)._\n\n> _**Note on API Quota Costs:** Most tools are highly efficient. `getVideoDetails`, `getChannelStatistics`, and `getTrendingVideos` cost only **1 unit** per call. The `getTranscripts` tool has **0** API cost. The new `getVideoComments` tool has a variable cost: the base call is **1 unit**, but if you request replies (by setting `maxReplies > 0`), it costs an **additional 1 unit for each top-level comment** it fetches replies for. The search-based tools are the most expensive: `searchVideos` costs **100 units** and `getChannelTopVideos` costs **101 units**._\n\n## Advanced Usage & Local Development\n\nIf you wish to contribute, modify the server, or run it locally outside of an MCP client's managed environment:\n\n### Prerequisites\n\n- Node.js (version specified in `package.json` engines field - currently `>=20.0.0`)\n- npm (usually comes with Node.js)\n- A YouTube Data API v3 Key (see [YouTube API Setup](#youtube-api-setup))\n\n### Local Setup\n\n1. **Clone the repository:**\n\n ```bash\n git clone https://github.com/kirbah/mcp-youtube.git\n cd mcp-youtube\n ```\n\n2. **Install dependencies:**\n\n ```bash\n npm ci\n ```\n\n3. **Configure Environment:**\n Create a `.env` file in the root by copying `.env.example`:\n ```bash\n cp .env.example .env\n ```\n Then, edit `.env` to add your `YOUTUBE_API_KEY`:\n ```\n YOUTUBE_API_KEY=your_youtube_api_key_here\n MDB_MCP_CONNECTION_STRING=your_mongodb_connection_string_here\n ```\n\n### Development Scripts\n\n```bash\n# Run in development mode with live reloading\nnpm run dev\n\n# Build for production\nnpm run build\n\n# Run the production build (after npm run build)\nnpm start\n\n# Lint files\nnpm run lint\n\n# Run tests\nnpm run test\nnpm run test -- --coverage # To generate coverage reports\n\n# Inspect MCP server using the Model Context Protocol Inspector\nnpm run inspector\n```\n\n### Local Development with an MCP Client\n\nTo have an MCP client run your _local development version_ (instead of the published NPM package):\n\n1. Ensure you have a script in `package.json` for a non-watching start, e.g.:\n\n ```json\n \"scripts\": {\n \"start:client\": \"tsx ./src/index.ts\"\n }\n ```\n\n2. Configure your MCP client to spawn this local script:\n ```json\n {\n \"mcpServers\": {\n \"youtube_local_dev\": {\n \"command\": \"npm\",\n \"args\": [\"run\", \"start:client\"],\n \"working_directory\": \"/absolute/path/to/your/cloned/mcp-youtube\",\n \"env\": {\n \"YOUTUBE_API_KEY\": \"YOUR_LOCAL_DEV_API_KEY_HERE\"\n }\n }\n }\n }\n ```\n _Note on the env block above: Setting YOUTUBE_API_KEY directly in the env block for the client configuration is one way to provide the API key. Alternatively, if your server correctly loads its .env file based on the working_directory, you might not need to specify it in the client's env block, as long as your local .env file in the project root contains the YOUTUBE_API_KEY. The working_directory path must be absolute and correct for the server to find its .env file._\n\n## YouTube API Setup\n\n1. Go to the [Google Cloud Console](https://console.cloud.google.com/).\n2. Create a new project or select an existing one.\n3. In the navigation menu, go to \"APIs & Services\" > \"Library\".\n4. Search for \"YouTube Data API v3\" and **Enable** it for your project.\n5. Go to \"APIs & Services\" > \"Credentials\".\n6. Click \"+ CREATE CREDENTIALS\" and choose \"API key\".\n7. Copy the generated API key. This is your `YOUTUBE_API_KEY`.\n8. **Important Security Step:** Restrict your API key to prevent unauthorized use. Click on the API key name, and under \"API restrictions,\" select \"Restrict key\" and choose \"YouTube Data API v3.\" You can also add \"Application restrictions\" (e.g., IP addresses) if applicable.\n\n## System Requirements\n\n- Node.js: `>=20.0.0` (as specified in `package.json`)\n- npm (for managing dependencies and running scripts)\n\n## Deep Dive: `findConsistentOutlierChannels` Tool\n\nThe `findConsistentOutlierChannels` tool is designed to identify emerging or established YouTube channels that consistently outperform their size within a specific niche. This tool is particularly useful for content creators, marketers, and analysts looking for high-potential channels.\n\n**Important Note:** This tool **requires a MongoDB connection** to store and analyze channel data. Without `MDB_MCP_CONNECTION_STRING` configured, this tool will not be available.\n\n### Internal Logic Overview\n\nThe tool operates through a multi-phase analysis process, leveraging both YouTube Data API and a MongoDB database:\n\n1. **Candidate Search (Phase 1):**\n - Uses the provided `query` to search for relevant videos and channels on YouTube.\n - Filters initial results based on `videoCategoryId` and `regionCode` if specified.\n - Collects a broad set of potential channels for deeper analysis.\n\n2. **Channel Filtering (Phase 2):**\n - Retrieves detailed statistics for candidate channels (subscribers, total views, video count).\n - Filters channels based on `channelAge` (e.g., 'NEW' for channels under 6 months, 'ESTABLISHED' for 6-24 months).\n - Ensures channels meet a minimum video count to be considered for consistency.\n\n3. **Deep Analysis (Phase 3):**\n - For each filtered channel, fetches their recent top-performing videos.\n - Calculates a \"viral factor\" for each video (e.g., views relative to subscriber count).\n - Assesses the `consistencyLevel` (e.g., 'MODERATE' for ~30% of videos showing outlier performance, 'HIGH' for ~50%).\n - Determines `outlierMagnitude` (e.g., 'STANDARD' for views > subscribers, 'STRONG' for views > 3x subscribers).\n\n4. **Ranking & Formatting (Phase 4):**\n - Ranks channels based on their consistency, outlier magnitude, and overall performance within the niche.\n - Formats the results into a token-optimized structure suitable for LLMs, including key channel metrics and examples of outlier videos.\n\n### Key Parameters Controlling the Flow\n\nThe behavior of this tool is primarily controlled by the following parameters:\n\n- `query` (string, required): The central topic or niche to analyze (e.g., \"DIY home repair\", \"quantum computing explained\").\n- `channelAge` (enum: \"NEW\", \"ESTABLISHED\", default: \"NEW\"): Focuses the search on emerging or more mature channels.\n- `consistencyLevel` (enum: \"MODERATE\", \"HIGH\", default: \"MODERATE\"): Sets the threshold for how consistently a channel's videos must perform as outliers.\n- `outlierMagnitude` (enum: \"STANDARD\", \"STRONG\", default: \"STANDARD\"): Defines how significantly a video's performance must exceed typical expectations (e.g., views vs. subscribers) to be considered an \"outlier.\"\n- `videoCategoryId` (string, optional): Narrows the search to a specific YouTube category ID.\n- `regionCode` (string, optional): Targets channels relevant to a particular geographical region.\n- `maxResults` (number, default: 10): Limits the number of top outlier channels returned.\n\n## Security Considerations\n\n- **API Key Security:** Your `YOUTUBE_API_KEY` is sensitive. Never commit it directly to your repository. Use environment variables (e.g., via a `.env` file which should be listed in `.gitignore`).\n- **API Quotas:** The YouTube Data API has a daily usage quota (default is 10,000 units). All tool calls deduct from this quota. Monitor your usage in the Google Cloud Console and be mindful of the cost of each tool. For a detailed breakdown of costs per API method, see the [official documentation](https://developers.google.com/youtube/v3/determine_quota_cost).\n- **Input Validation:** The server uses Zod for robust input validation for all tool parameters, enhancing security and reliability.\n\n## License\n\nThis project is licensed under the **MIT License**. See the [LICENSE](https://github.com/kirbah/mcp-youtube/blob/main/LICENSE) file for details.\n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"iconType","image","upstream",{"_98":99,"_100":101,"_102":103,"_104":105,"_106":-5,"_107":108},"requiredSecrets",[],"tags",[97],"assets",[],"stats",{"_95":82,"_96":82},"ratingAvg","reviewCount","youtube-api","topics",[109,110,97],"license","MIT","language","TypeScript","registryName","ai.smithery/kirbah-mcp-youtube","homepage","packages",[],"mcp","mcp-server","ENV",{"_113":114,"_115":116,"_117":118},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]