mcp-server

tmnestor/mcp-server

3.2

If you are the rightful owner of mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

A Model Context Protocol (MCP) server that provides YouTube video search capabilities for use with Claude Code in VS Code.

Tools
2
Resources
0
Prompts
0

YouTube Video Search MCP Server

A Model Context Protocol (MCP) server that provides YouTube video search capabilities for use with Claude Code in VS Code. This project includes both an MCP server for Claude integration and a standalone Python script for cost-effective batch video searches.

Overview

This project provides YouTube video search functionality through:

  1. MCP Server (mcp_videos.py) - Integrates with Claude Code for interactive searches and cost-effective file operations
  2. Standalone Script (save_videos.py) - Alternative batch processing tool for direct command-line usage

Features

  • Interactive Search: Search YouTube videos through Claude Code with natural language queries
  • Cost-Effective File Operations: Use Claude for search queries, Python for formatting and saving (reduces AI costs)
  • Dual Tool MCP Server:
    • get_videos - Display search results in Claude Code interface
    • save_videos - Search and save formatted results to files
  • Multiple Output Formats: Save results as Markdown, JSON, or plain text files
  • Natural Language Interface: Ask Claude to search and save with conversational commands
  • Flexible Configuration: Custom result limits, file paths, and output formats
  • Rich Console Output: Colorful, styled terminal interface (standalone script)
  • Structured Data: Complete video metadata including title, channel, duration, views, and descriptions

Installation

Prerequisites

  • Python 3.11.11+
  • uv package manager (recommended)

Setup

# Clone the repository
git clone <repository-url>
cd mcp-server

# Install dependencies
uv sync

Usage

Method 1: MCP Server with Claude Code (Recommended)

For interactive searches with cost-effective file operations through natural language:

Step 1: Configure Claude Code MCP

Create a .clauderc file in your project directory:

touch .clauderc

Add this configuration to .clauderc:

{
  "mcpServers": {
    "youtube-search": {
      "command": "uv",
      "args": ["run", "python", "mcp_videos.py"],
      "cwd": "."
    }
  }
}
Step 2: Start Claude Code with MCP
# Make sure you're in the mcp-server directory
cd /Users/tod/Desktop/mcp-server

# Start Claude Code with MCP
claude --mcp-config .clauderc
Step 3: Use Natural Language Commands

Once Claude Code starts with MCP support, you can use natural language to search and save videos:

Example Commands:

You: Find me 5 Python tutorial videos and save them as markdown to python_tutorials.md

You: Search for "Docker containers" and save the top 10 results as JSON to docker_results.json

You: Look for React hooks tutorials, get 8 videos, and save them as plain text to react_hooks.txt

You: Search for "machine learning basics" and save 15 results as markdown to ml_basics.md

Available MCP Tools:

  • get_videos - Display search results in Claude interface for browsing
  • save_videos - Search and save formatted results to files (cost-effective)

Benefits:

  • Natural language interface - Ask Claude in plain English
  • Cost-effective - Claude handles the search query, Python handles formatting/saving
  • Flexible - Custom result counts, file paths, and output formats
  • Interactive - Browse results first with get_videos, then save with save_videos
Troubleshooting

MCP server not found:

  • Ensure you're in the correct directory
  • Check that uv is installed: uv --version
  • Verify dependencies: uv sync

No tools available:

  • Make sure you started Claude Code with claude --mcp-config .clauderc
  • Check the .clauderc file is in the current directory
  • Restart Claude Code

Method 2: Standalone Python Script (Alternative)

For direct command-line usage without Claude Code:

# Basic usage - saves to search_results.md
uv run python save_videos.py "Docker tutorials"

# Custom options
uv run python save_videos.py "React hooks" -n 15 -o react_videos.txt -f txt

# JSON format for further processing
uv run python save_videos.py "Machine learning" -f json -o ml_videos.json

Available Options:

  • search (required): Search query for YouTube videos
  • -n, --max-results: Maximum number of results (default: 10)
  • -o, --output: Output file path (default: search_results.md)
  • -f, --format: Output format - txt, json, or md (default: md)

More Usage Examples:

# Search with custom result count
uv run python save_videos.py "React tutorials" --max-results 15

# Save as plain text
uv run python save_videos.py "DevOps practices" -f txt -o devops.txt

# Combine short flags  
uv run python save_videos.py "AI machine learning" -n 20 -o ai_videos.json -f json

Note: The --help flag has a known bug in typer 0.16.0, but all functionality works perfectly. Refer to the usage examples above.

MCP Tool Usage

The MCP server provides two tools for different use cases:

Tool 1: get_videos - Interactive Browsing

Display search results in Claude Code interface for interactive browsing.

Parameters:

  • search (string): Search query
  • max_results (integer): Maximum number of results to return

Usage through Claude Code:

You: Show me 5 Python tutorial videos
You: Find Docker containerization tutorials, limit to 3 results

Tool 2: save_videos - Cost-Effective File Operations

Search and save formatted results directly to files using Python (reduces AI costs).

Parameters:

  • search (string): Search query
  • max_results (integer): Maximum number of results to return
  • output_file (string): Output file path
  • format_type (string): Output format - 'md', 'json', or 'txt'

Usage through Claude Code:

You: Search for "React hooks" and save 10 results as JSON to react_hooks.json
You: Find Python tutorials, get 15 videos, save as markdown to python_tutorials.md
You: Look for Docker videos and save 8 results as plain text to docker_videos.txt

Sample Tool Response

get_videos output (displayed in Claude):

Title: Python Tutorial - Python Full Course for Beginners
Channel: Programming with Mosh
Duration: 6:14:07
Description: Python tutorial for beginners - Learn Python programming...
Views: 2.1M views
URL: https://www.youtube.com/watch?v=_uQrJ0TkZlc
Published: 2 years ago
---
[Additional results...]

save_videos output:

Successfully saved 10 videos to python_tutorials.md in md format.

Architecture

The project uses a simple modular architecture:

  • yt_helper.py - Core YouTube search functionality using the youtube-search library
  • mcp_videos.py - Enhanced MCP server with dual tools:
    • get_videos - Interactive search and display
    • save_videos - Cost-effective search and file operations
  • save_videos.py - Alternative standalone CLI script with typer and rich console output

Development

Testing

Test the MCP server (recommended):

# Start Claude Code with MCP
claude --mcp-config .clauderc

# Then test both tools:
# 1. Interactive browsing:
#    "Show me 5 Python tutorial videos"
# 2. File saving:  
#    "Search for Docker tutorials and save 10 results as JSON to test_docker.json"

Test the standalone script (alternative):

# Test basic search
uv run python save_videos.py "Python tutorials" -n 3

# Test different formats
uv run python save_videos.py "Docker" -f json -o test.json

# Test with all options
uv run python save_videos.py "JavaScript frameworks" --max-results 5 --output js_test.txt --format txt

Note: The --help flag has a known bug in typer 0.16.0, but all functionality works perfectly. Refer to the usage examples in this README.

Dependencies

  • mcp - Model Context Protocol implementation
  • youtube-search - YouTube search functionality
  • typer - Modern CLI framework with rich features
  • rich - Rich console output with colors and styling

License

This project is provided as an example implementation of MCP server functionality.