Skip to main content
Glama
will-ness-ai

YouTube Tools MCP Server

by will-ness-ai
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Hybrid

YouTube Tools MCP Server

A powerful Model Context Protocol (MCP) server that enables AI assistants to search YouTube and extract video transcripts. Built with TypeScript and designed for seamless integration with Claude Desktop and other MCP-compatible clients.

šŸŽÆ What is this?

This MCP server bridges the gap between AI assistants and YouTube content by providing comprehensive YouTube integration capabilities. It allows you to:

  • Search YouTube videos using the official YouTube Data API v3

  • Extract full transcripts from any YouTube video (when available)

  • Store and retrieve video summaries using a local libsql database

  • Filter search results by date, duration, quality, and more

  • Get timestamped transcript segments for precise referencing

  • Support multiple languages for international content

  • Handle various YouTube URL formats automatically

Perfect for content discovery, analysis, research, accessibility, and AI-powered video content workflows.

Related MCP server: mcp-server-youtube

āœØ Features

  • šŸ” YouTube Video Search: Search YouTube using the official YouTube Data API v3

  • šŸŽ¬ YouTube Transcript Extraction: Get complete transcripts from YouTube videos using RapidAPI

  • šŸ’¾ Video Summary Storage: Store and retrieve video summaries using local libsql database

  • šŸŽÆ Advanced Search Filters: Filter by date, duration, quality, view count, and more

  • šŸ”— Flexible Input Formats: Supports video IDs, full URLs, short URLs, and embed URLs

  • šŸŒ Multi-Language Support: Extract transcripts in different languages when available

  • āš” Smart Error Handling: Comprehensive error handling with clear, actionable messages

  • šŸ› ļø MCP Protocol Compliant: Built with the official MCP SDK for maximum compatibility

  • šŸ”‘ Official API Integration: Uses YouTube Data API v3 and RapidAPI for reliable service

  • šŸ’» CLI Tool Included: Command-line interface for direct transcript extraction

šŸš€ Quick Start

Prerequisites

  • Node.js 18+

  • pnpm (recommended) or npm

  • Claude Desktop (for usage)

  • YouTube Data API v3 Key (for search functionality)

  • RapidAPI Account (for transcript extraction)

Installation

  1. Clone and install dependencies:

    git clone <repository-url>
cd youtube-tools-mcp
pnpm install

  2. Set up API Keys:

    YouTube Data API v3 (for search):

    • Go to Google Cloud Console

    • Create a new project or select existing one

    • Enable the YouTube Data API v3

    • Create credentials (API key)

    • Copy your YouTube API key

    RapidAPI (for transcripts):

  3. Configure environment:

    # Create .env file and add your API keys:
YOUTUBE_API_KEY=your_youtube_api_key_here
RAPIDAPI_KEY=your_rapidapi_key_here

# Optional: Specify custom database path for video summaries
DATABASE_PATH=./video_summaries.db

  4. Build the project:

    pnpm run build

  5. Test your setup:

    node temp/test-rapidapi.js

  6. Configure Claude Desktop:

    Add to your Claude Desktop config file (~/Library/Application Support/Claude/claude_desktop_config.json):

    {
  "mcpServers": {
    "youtube-tools": {
      "command": "node",
      "args": ["/absolute/path/to/youtube-tools-mcp/build/index.js"],
      "env": {
        "YOUTUBE_API_KEY": "your_youtube_api_key_here",
        "RAPIDAPI_KEY": "your_rapidapi_key_here",
        "DATABASE_PATH": "/absolute/path/to/youtube-tools-mcp/video_summaries.db"
      }
    }
  }
}

    Important:

    • Replace /absolute/path/to/youtube-tools-mcp with your actual project path

    • Replace the API keys with your actual keys

    • The DATABASE_PATH is optional - if omitted, it defaults to video_summaries.db in the project root

  7. Restart Claude Desktop completely.

  8. Test it out! Try asking Claude:

    "Get the transcript for this YouTube video: https://www.youtube.com/watch?v=2nkiHeoPTqQ"

šŸ’» CLI Usage

You can also use the included command-line tool:

# Basic usage
node cli.js 2nkiHeoPTqQ

# With full URL
node cli.js "https://www.youtube.com/watch?v=2nkiHeoPTqQ"

# Specify language
node cli.js 2nkiHeoPTqQ --language es

# Save to file
node cli.js 2nkiHeoPTqQ --output transcript.txt

# JSON format
node cli.js 2nkiHeoPTqQ --json

# Hide timestamps
node cli.js 2nkiHeoPTqQ --no-timestamps

# Show help
node cli.js --help

šŸ“– Usage Examples

Once configured with Claude Desktop, you can use natural language to interact with YouTube:

Search Examples

Basic search:

"Search YouTube for 'javascript tutorial' videos"

Search with filters:

"Find recent React tutorials from the last month, ordered by view count"

Search for specific content:

"Search for Python programming videos that are medium length and high definition"

Transcript Examples

Get transcript from URL:

"Get the transcript for this YouTube video: https://www.youtube.com/watch?v=2nkiHeoPTqQ"

Use just the video ID:

"Extract transcript from YouTube video ID 2nkiHeoPTqQ"

Specify language:

"Get the Spanish transcript for this video: https://www.youtube.com/watch?v=example"

Works with different URL formats:

  • Full URL: https://www.youtube.com/watch?v=dQw4w9WgXcQ

  • Short URL: https://youtu.be/dQw4w9WgXcQ

  • Embed URL: https://www.youtube.com/embed/dQw4w9WgXcQ

  • Video ID: dQw4w9WgXcQ

Video Summary Examples

Store a video summary:

"Store this summary for video dQw4w9WgXcQ: This is a classic music video featuring Rick Astley's hit song Never Gonna Give You Up."

Retrieve a stored summary:

"Get the stored summary for video ID dQw4w9WgXcQ"

Check if a summary exists:

"Do we have a summary stored for this YouTube video: https://www.youtube.com/watch?v=dQw4w9WgXcQ"

šŸ”§ Available Tools

search_youtube

Search for YouTube videos using the official YouTube Data API v3.

Parameters:

  • query (required): Search query for YouTube videos

  • maxResults (optional): Maximum number of results to return (1-50, default: 10)

  • order (optional): Order of results - "relevance", "date", "rating", "viewCount", "title" (default: "relevance")

  • publishedAfter (optional): Return videos published after this date (RFC 3339 format)

  • publishedBefore (optional): Return videos published before this date (RFC 3339 format)

  • videoDuration (optional): Filter by duration - "any", "short", "medium", "long" (default: "any")

  • videoDefinition (optional): Filter by definition - "any", "high", "standard" (default: "any")

Sample Output:

YouTube Search Results for: "javascript tutorial"
šŸ“Š Total Results Available: 1000000
šŸ“‹ Results Returned: 3
šŸ”„ Ordered by: relevance

--- SEARCH RESULTS ---
1. **JavaScript Tutorial for Beginners**
   šŸ“ŗ Channel: Programming with Mosh
   šŸ“… Published: 1/15/2023
   šŸ”— URL: https://www.youtube.com/watch?v=W6NZfCO5SIk
   šŸ“ Video ID: W6NZfCO5SIk
   šŸ“„ Description: Learn JavaScript fundamentals in this comprehensive tutorial...

2. **Modern JavaScript Course**
   šŸ“ŗ Channel: The Net Ninja
   šŸ“… Published: 3/22/2023
   šŸ”— URL: https://www.youtube.com/watch?v=iWOYAxlnaww
   šŸ“ Video ID: iWOYAxlnaww
   šŸ“„ Description: Master modern JavaScript with this complete course...

get_youtube_transcript

Extract complete transcripts from YouTube videos using RapidAPI.

Parameters:

  • videoId (required): YouTube video ID or any YouTube URL format

  • language (optional): Language code for transcript (e.g., "en", "es", "fr", default: "en")

Sample Output:

YouTube Transcript for Video ID: W6NZfCO5SIk
šŸ“Š Total Segments: 245
ā±ļø Duration: 1:23:45

--- TRANSCRIPT ---
[0:00] Welcome to this JavaScript tutorial for beginners
[0:05] In this video we're going to learn the fundamentals
[0:12] Let's start with variables and data types
...

storeVideoSummary

Store or update a video summary in the local database.

Parameters:

  • videoId (required): YouTube video ID

  • summary (required): Video summary text to store

Sample Output:

Successfully stored summary for video ID: W6NZfCO5SIk

fetchExistingVideoSummary

Fetch an existing video summary from the local database.

Parameters:

  • videoId (required): YouTube video ID

Sample Output:

Summary for video ID: W6NZfCO5SIk

This is a comprehensive JavaScript tutorial covering fundamentals like variables, functions, and DOM manipulation. Perfect for beginners looking to learn modern JavaScript development.

Note: Returns "No summary found" if no summary exists for the given video ID.

šŸ› ļø Development

Available Scripts

  • pnpm run build - Compile TypeScript to JavaScript

  • pnpm run dev - Watch mode for development (auto-rebuild on changes)

  • pnpm start - Run the compiled server directly

  • pnpm run test - Test YouTube transcript functionality

  • pnpm run test-mcp - Test MCP server functionality

  • pnpm run test-search - Test YouTube search API functionality

  • pnpm run test-mcp-search - Test MCP server with search functionality

Project Structure

youtube-tools-mcp/
ā”œā”€ā”€ src/
ā”‚   ā”œā”€ā”€ index.ts          # Main MCP server implementation
ā”‚   ā””ā”€ā”€ database.ts       # Database service for video summaries
ā”œā”€ā”€ build/                # Compiled JavaScript output
ā”œā”€ā”€ docs/                 # Documentation and examples
ā”œā”€ā”€ temp/                 # Test files and utilities
ā”œā”€ā”€ video_summaries.db    # Local libsql database (auto-created)
ā”œā”€ā”€ package.json          # Dependencies and scripts
ā”œā”€ā”€ .env.example          # Environment variables template
ā””ā”€ā”€ README.md            # This file

Testing

Test the server functionality:

# Test YouTube transcript extraction
pnpm run test

# Test YouTube search API
pnpm run test-search

# Test MCP server protocol
pnpm run test-mcp

# Test MCP server with search functionality
pnpm run test-mcp-search

# Test database functionality (video summary storage/retrieval)
node temp/test-database-functionality.js

# Manual server test (runs until Ctrl+C)
pnpm start

āš ļø Error Handling

The server provides clear error messages for common scenarios:

Error

Cause

Solution

"Transcript is disabled"

Video creator disabled transcripts

Try a different video

"No transcript found"

No transcript in requested language

Try "en" or check available languages

"Video unavailable"

Private, deleted, or restricted video

Verify the video is public and accessible

"Invalid video ID"

Malformed URL or ID

Check the YouTube URL format

šŸ”§ Troubleshooting

Server not appearing in Claude Desktop?

  1. Verify the absolute path in your config is correct

  2. Ensure the project built successfully (pnpm run build)

  3. Restart Claude Desktop completely

  4. Check Claude's logs: ~/Library/Logs/Claude/mcp*.log

Tool calls failing?

  1. Test the server manually: pnpm start

  2. Verify the video has transcripts available

  3. Try with a different video

  4. Check the video is public and not region-restricted

šŸ“¦ Dependencies

šŸ¤ Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

šŸ“„ License

MIT License - see LICENSE file for details.

Built with ā¤ļø using the Model Context Protocol

Available Tools

4 tools
fetchExistingVideoSummaryA

Fetch an existing video summary from the database

ParametersJSON Schema
NameRequiredDescriptionDefault
videoIdYesYouTube video ID

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description reveals no details about return values, error handling, or behavior when no summary exists. Without annotations (readOnlyHint, destructiveHint), the agent has no explicit indication that this is a safe read operation, though the word 'fetch' implies it. It also does not mention prerequisites like a valid videoId or database accessibility.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that directly states the tool's action without unnecessary words. It earns a high score for conciseness and clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter retrieval tool, the description gives the core purpose but omits outcome details such as whether a missing summary returns null or an error. Since there is no output schema, the agent must infer the return type, leaving some ambiguity in edge cases. This is adequate but not fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema fully documents the single parameter videoId as 'YouTube video ID', so the description need not elaborate. The description itself does not mention the parameter, but the schema covers it adequately; baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: fetching an existing summary from a database. It distinguishes from siblings (get transcript, search, store) by specifying 'existing video summary' and 'database', making its purpose unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when a videoId is available and a previously stored summary is needed, but it does not explicitly reference alternative tools or state when not to use it. Sibling tools like get_youtube_transcript and storeVideoSummary are absent from the guidance, so the agent must infer usage context from the name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_youtube_transcriptB

Extract transcript from a YouTube video

ParametersJSON Schema
NameRequiredDescriptionDefault
videoIdYesYouTube video ID or full YouTube URL
languageNoLanguage code for transcript (optional, e.g., "en", "es", "fr")en

TDQS

B3/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry behavioral transparency. It does not disclose expected output format, limitations (e.g., language availability, video accessibility), or whether the tool returns plain text, timestamps, or a structured object. The description adds no behavioral details beyond what the tool name implies.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no wasted words. It efficiently communicates the primary purpose, earning a high score for conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is relatively simple with two parameters and no annotations or output schema, but the description is too sparse to be complete. It does not explain what the transcript output looks like, how language is handled, or any edge cases, leaving meaningful gaps for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% (both videoId and language have descriptions), so the schema fully documents parameters. The description adds no extra meaning about parameters, but baseline 3 is appropriate because the schema handles the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the specific verb 'Extract' and a clear resource ('transcript from a YouTube video'), which immediately distinguishes it from siblings like search_youtube, fetchExistingVideoSummary, and storeVideoSummary. There is no ambiguity about what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives, no prerequisites, and no examples. It merely states the action without contextualizing scenarios (e.g., when a user needs transcript text vs. a summary).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_youtubeB

Search for YouTube videos using the YouTube Data API v3

ParametersJSON Schema
NameRequiredDescriptionDefault
orderNoOrder of results (relevance, date, rating, viewCount, title)relevance
queryYesSearch query for YouTube videos
maxResultsNoMaximum number of results to return (1-50, default: 10)
videoDurationNoFilter by video durationany
publishedAfterNoReturn videos published after this date (RFC 3339 format, e.g., '2023-01-01T00:00:00Z')
publishedBeforeNoReturn videos published before this date (RFC 3339 format, e.g., '2024-01-01T00:00:00Z')
videoDefinitionNoFilter by video definitionany

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose whether this operation is read-only, requires authentication, has rate limits, or returns certain data. It only mentions the API name, giving no behavioral transparency beyond what is obvious from the tool name.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, direct sentence that states the tool's purpose without waste. It is front-loaded and appropriately concise for a simple search tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With seven parameters, no annotations, and no output schema, the description does not explain return values, result format, or operational constraints. It provides no context about pagination, sorting defaults, or how results relate to sibling tools, making it insufficiently complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

All seven parameters are documented in the schema with descriptions, including enums and defaults. The description adds no parameter-specific information beyond the schema, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific action (search) on a specific resource (YouTube videos) and names the underlying API. This distinguishes it from sibling tools that handle transcripts and summaries.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like get_youtube_transcript or storeVideoSummary. There are no exclusions or contextual hints beyond the basic search function.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

storeVideoSummaryB

Store or update a video summary in the database

ParametersJSON Schema
NameRequiredDescriptionDefault
summaryYesVideo summary text to store
videoIdYesYouTube video ID

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full behavioral burden. It states the write intent but fails to disclose key details such as whether an existing summary is overwritten, whether it upserts vs. inserts, required permissions, or what the response looks like. The ambiguous 'store or update' phrasing leaves uncertainty.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no filler, immediately conveying the core function. It is appropriately sized and front-loaded with the action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Even though the tool is simple with two params and full schema coverage, the absence of annotations and output schema leaves the description incomplete. It does not explain upsert/overwrite behavior, return values, or error conditions, which are essential for reliable invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, with both parameters fully described in the input schema. The description adds no additional semantic detail beyond the schema, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the verb ('Store or update') and resource ('video summary in database'), and the write intent distinguishes it from sibling read/search tools like fetchExistingVideoSummary and get_youtube_transcript. This makes the purpose unambiguous and specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for persisting a summary, and the read/write distinction from siblings is apparent, but it does not explicitly state when to use this tool vs alternatives or provide any exclusions. No alternative tools are named for update/creation scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv1.0.0
    • First observedfetchExistingVideoSummary
    • First observedget_youtube_transcript
    • First observedsearch_youtube
    • First observedstoreVideoSummary
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: searching YouTube, fetching transcripts, and retrieving/storing summaries. There is no overlap between tool responsibilities, so an agent can easily select the correct tool for a task.

Naming Consistency2/5

The tool names mix conventions: 'get_youtube_transcript' and 'search_youtube' use snake_case and include 'youtube', while 'fetchExistingVideoSummary' and 'storeVideoSummary' use camelCase and omit the service name. The inconsistent verb choices (get vs fetch, store vs search) further reduce predictability.

Tool Count5/5

With only 4 tools, the server is tightly scoped to its purpose of YouTube video search, transcript retrieval, and summary management. Each tool is necessary and there is no bloat, making the count appropriate for the domain.

Completeness4/5

The tool set covers the core workflows: search, transcript, and summary storage/retrieval. A delete summary tool is missing, but the store operation handles both create and update, so the surface is largely complete for the implied use case.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers