by kirbah
Retrieve token‑optimized, structured YouTube data—including video details, transcripts, channel statistics, trending lists, and comments—for direct consumption by large language models.
Provides a Model Context Protocol (MCP) server that exposes a suite of tools for accessing YouTube Data API v3. Each tool returns lean, JSON‑structured payloads designed to minimize token usage when fed to LLMs, covering video search, details, transcripts, channel stats, trending videos, categories, comments, and niche outlier analysis.
{
"mcpServers": {
"youtube": {
"command": "npx",
"args": ["-y", "@kirbah/mcp-youtube"],
"env": {
"YOUTUBE_API_KEY": "<YOUR_YOUTUBE_API_KEY>",
"MDB_MCP_CONNECTION_STRING": "<YOUR_MONGODB_CONNECTION_STRING>"
}
}
}
}
npx -y @kirbah/mcp-youtube and listen for tool calls.Q: Do I need MongoDB?
A: It is optional. Without it the server runs, but caching and the findConsistentOutlierChannels tool will be unavailable.
Q: How are API quota costs calculated?
A: Most tools cost 1 unit per call; searchVideos costs 100 units, getChannelTopVideos 101 units, and comment replies add 1 unit per top‑level comment with replies.
Q: Which Node.js version is required?
A: Node.js >= 20.0.0 as defined in package.json.
Q: Can I run the server locally for development?
A: Yes. Clone the repo, run npm ci, set up a .env file with your keys, then npm run dev or npm start.
Q: How do I limit the number of results returned?
A: Most tools accept maxResults (or similar) parameters; default values are defined in each tool’s schema.
High-efficiency YouTube MCP server: Get token-optimized, structured data for your LLMs using the YouTube Data API v3.
This Model Context Protocol (MCP) server empowers AI language models to seamlessly interact with YouTube. It's engineered to return lean, structured data, significantly reducing token consumption and making it ideal for cost-effective and performant LLM applications. Access a comprehensive suite of tools for video search, detail retrieval, transcript fetching, channel analysis, and trend discovery—all optimized for AI.
Built with MCP TypeScript Starter
This project follows the architecture defined in the MCP TypeScript Starter. If you are looking to build your own MCP server using these same patterns (Class-based Tools, Dependency Injection, and strict Type Safety), I recommend using that repository as your starting point.
The easiest way to use @kirbah/mcp-youtube is with an MCP-compatible client application (like Claude Desktop or a custom client).
Ensure you have a YouTube Data API v3 Key.
MongoDB Connection String (Optional): This server can use MongoDB to cache API responses and store analysis data, which significantly improves performance and reduces API quota usage. If you don't provide a connection string, the server will run without a database, but performance will be degraded, and you may hit API quota limits faster. You can get a free MongoDB Atlas cluster to obtain a connection string.
Important: If you use MongoDB, the server is hardcoded to use the database name youtube_niche_analysis. Your connection string must point to this database, and your user must have read/write permissions for it.
Configure your MCP client:
Add the following JSON configuration to your client, replacing "YOUR_YOUTUBE_API_KEY_HERE" with your actual API key.
{
"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"
}
}
}
}
npx can sometimes cause issues directly. If you encounter problems, try modifying the command as follows:
"command": "cmd",
"args": ["/k", "npx", "-y", "@kirbah/mcp-youtube"],
That's it! Your MCP client should now be able to leverage the YouTube tools provided by this server.
@kirbah/mcp-youtube?In the world of Large Language Models, every token counts. @kirbah/mcp-youtube is designed from the ground up with this principle in mind:
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) |
getVideoCategories |
Retrieves available YouTube video categories (ID and title) for a specific region, providing essential data only. | regionCode (optional string) |
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) |
findConsistentOutlierChannels |
Identifies channels that consistently perform as outliers within a specific niche. Requires a MongoDB connection. | niche (string), minVideos (optional number), maxChannels (optional number) |
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).
Note on API Quota Costs: Most tools are highly efficient.
getVideoDetails,getChannelStatistics, andgetTrendingVideoscost only 1 unit per call. ThegetTranscriptstool has 0 API cost. The newgetVideoCommentstool has a variable cost: the base call is 1 unit, but if you request replies (by settingmaxReplies > 0), it costs an additional 1 unit for each top-level comment it fetches replies for. The search-based tools are the most expensive:searchVideoscosts 100 units andgetChannelTopVideoscosts 101 units.
If you wish to contribute, modify the server, or run it locally outside of an MCP client's managed environment:
package.json engines field - currently >=20.0.0)Clone the repository:
git clone https://github.com/kirbah/mcp-youtube.git
cd mcp-youtube
Install dependencies:
npm ci
Configure Environment:
Create a .env file in the root by copying .env.example:
cp .env.example .env
Then, edit .env to add your YOUTUBE_API_KEY:
YOUTUBE_API_KEY=your_youtube_api_key_here
MDB_MCP_CONNECTION_STRING=your_mongodb_connection_string_here
# Run in development mode with live reloading
npm run dev
# Build for production
npm run build
# Run the production build (after npm run build)
npm start
# Lint files
npm run lint
# Run tests
npm run test
npm run test -- --coverage # To generate coverage reports
# Inspect MCP server using the Model Context Protocol Inspector
npm run inspector
To have an MCP client run your local development version (instead of the published NPM package):
Ensure you have a script in package.json for a non-watching start, e.g.:
"scripts": {
"start:client": "tsx ./src/index.ts"
}
Configure your MCP client to spawn this local script:
{
"mcpServers": {
"youtube_local_dev": {
"command": "npm",
"args": ["run", "start:client"],
"working_directory": "/absolute/path/to/your/cloned/mcp-youtube",
"env": {
"YOUTUBE_API_KEY": "YOUR_LOCAL_DEV_API_KEY_HERE"
}
}
}
}
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.
YOUTUBE_API_KEY.>=20.0.0 (as specified in package.json)findConsistentOutlierChannels ToolThe 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.
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.
The tool operates through a multi-phase analysis process, leveraging both YouTube Data API and a MongoDB database:
Candidate Search (Phase 1):
query to search for relevant videos and channels on YouTube.videoCategoryId and regionCode if specified.Channel Filtering (Phase 2):
channelAge (e.g., 'NEW' for channels under 6 months, 'ESTABLISHED' for 6-24 months).Deep Analysis (Phase 3):
consistencyLevel (e.g., 'MODERATE' for ~30% of videos showing outlier performance, 'HIGH' for ~50%).outlierMagnitude (e.g., 'STANDARD' for views > subscribers, 'STRONG' for views > 3x subscribers).Ranking & Formatting (Phase 4):
The behavior of this tool is primarily controlled by the following parameters:
query (string, required): The central topic or niche to analyze (e.g., "DIY home repair", "quantum computing explained").channelAge (enum: "NEW", "ESTABLISHED", default: "NEW"): Focuses the search on emerging or more mature channels.consistencyLevel (enum: "MODERATE", "HIGH", default: "MODERATE"): Sets the threshold for how consistently a channel's videos must perform as outliers.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."videoCategoryId (string, optional): Narrows the search to a specific YouTube category ID.regionCode (string, optional): Targets channels relevant to a particular geographical region.maxResults (number, default: 10): Limits the number of top outlier channels returned.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).This project is licensed under the MIT License. See the LICENSE file for details.
Please log in to share your review and rating for this MCP.
Explore related MCPs that share similar capabilities and solve comparable challenges
by lharries
Enables searching, reading, and sending personal WhatsApp messages and media through a Model Context Protocol (MCP) server, storing all data locally in SQLite and exposing controlled tools for LLMs like Claude.
by caol64
Automatically format Markdown articles and publish them to WeChat public accounts, supporting theme selection, image upload, and AI integration.
by korotovsky
Provides a powerful Model Context Protocol interface for Slack workspaces, enabling message retrieval, search, and optional posting via Stdio or SSE transports without requiring bot permissions.
by iFurySt
Provides authenticated access to XiaoHongShu (RedNote) notes, supporting keyword search, note retrieval by URL, and cookie persistence via a Model Context Protocol server.
by chigwell
Provides a full‑featured Telegram integration for MCP‑compatible clients, enabling programmatic access to chats, messages, contacts, profile management, and group administration.
by line
Integrates the LINE Messaging API with a Model Context Protocol server, enabling AI agents to send text, flex, broadcast messages, retrieve user profiles, and manage rich menus on a LINE Official Account.
by ZubeidHendricks
Provides a standardized interface for interacting with YouTube content, enabling video retrieval, transcript access, channel and playlist management, and advanced analytics through the Model Context Protocol.
by InditexTech
Provides Microsoft Teams integration via the Model Context Protocol, enabling reading, creating, replying to messages and mentioning members.
by EnesCinr
Interact with Twitter to post tweets and search tweets programmatically via an MCP server.
{
"mcpServers": {
"youtube": {
"command": "npx",
"args": [
"-y",
"@kirbah/mcp-youtube"
],
"env": {
"YOUTUBE_API_KEY": "<YOUR_YOUTUBE_API_KEY>",
"MDB_MCP_CONNECTION_STRING": "<YOUR_MONGODB_CONNECTION_STRING>"
}
}
}
}claude mcp add youtube npx -y @kirbah/mcp-youtube