MCP 服务器

YouTube Search & Download MCP Server

Enables searching, retrieving metadata, and downloading YouTube videos or audio without requiring an API key. It utilizes yt-dlp to support media retrieval and playlist management within MCP-compliant clients like Claude and Cursor.

README

<div align="center"> <img width="400" alt="logo" src="https://github.com/user-attachments/assets/4ab98cc2-d0f7-4953-840f-d7fb43d4b893" /> <h1 align="center">YouTube Search & Download MCP Server</h1> <p align="center"> <strong>YouTube API 키 없이 동영상을 검색하고 다운로드하는 MCP 서버</strong> <br /> <a href="https://github.com/easyhak/youtube-search-mcp/issues/new/choose">Bug Report</a> · <a href="https://github.com/easyhak/youtube-search-mcp/issues/new/choose">Feature Request</a> </p>

<p align="center"> <a href="README.md"><strong>English</strong></a> · <a href="README_ko.md"><strong>한국어</strong></a> </p> </div>

🚀 What is YouTube Search MCP?

This is a production-quality Model Context Protocol (MCP) server that allows you to search, get information about, and download YouTube videos and audio without needing a YouTube API key. It's designed to work seamlessly with MCP clients like Claude Desktop and Cursor.

The server is built with / for robust backend operations and FastMCP for a high-performance server framework.

✨ Key Features

No API Key Required: Search and download freely using yt-dlp.
Easy Installation: Simple setup with uv or pip. Works seamlessly with MCP clients.
Video & Audio Downloads: Download content in various formats (mp4, mkv, mp3, wav, etc.) and qualities.
Playlist Support: Search for playlists, get playlist details, and retrieve all videos from any playlist.
Rich Metadata: Get detailed video information, including duration, view count, and chapters.
Client Compatibility: Works great with Claude, Cursor, and other MCP-compliant clients.
Robust & Type-Safe: Built on a SOLID architecture with full type safety using Pydantic.

🏁 Getting Started (For Users)

Prerequisites

Python 3.10 or higher
uv (recommended) or pip
FFmpeg (must be installed and available in your system's PATH)
- Windows: choco install ffmpeg (with Chocolatey) or download from gyan.dev/ffmpeg
- macOS: brew install ffmpeg
- Linux: sudo apt install ffmpeg (Ubuntu/Debian) or sudo dnf install ffmpeg (Fedora)

Installation

Install the package using uv (recommended) or pip:

# Using uv (recommended)
uv pip install youtube-search-mcp

# Or using pip
pip install youtube-search-mcp

Running the Server

After installation, you can run the server directly:

youtube-search-mcp

💻 Client Configuration

Configure your MCP client to connect to the server.

For Claude Desktop or Cursor:

Add this to your MCP client configuration (usually claude_desktop_config.json):

{
  "mcpServers": {
    "youtube-search": {
      "command": "youtube-search-mcp"
    }
  }
}

Or if using uvx (no installation required):

{
  "mcpServers": {
    "youtube-search": {
      "command": "uvx",
      "args": ["youtube-search-mcp"]
    }
  }
}

🔧 Configuration

You can customize the server's behavior by setting environment variables. These can be added to your MCP client configuration (e.g., claude_desktop_config.json) or set via a .env file in the project root.

Variable	Description	Default
`YT_MCP_DOWNLOAD_DIR`	Directory where videos/audio will be saved	`downloads`
`YT_MCP_DEFAULT_VIDEO_QUALITY`	Default video quality (`best`, `high`, `medium`, `low`)	`best`
`YT_MCP_DEFAULT_MAX_RESULTS`	Number of search results to return by default	`10`
`YT_MCP_LOG_LEVEL`	Logging level (`DEBUG`, `INFO`, `WARNING`, `ERROR`)	`INFO`

🛠️ For Developers & Contributors

Interested in contributing? Here’s how to set up your development environment.

Prerequisites

Git
Python 3.10+
uv (recommended) or pip
FFmpeg (must be installed and available in your system's PATH for development)
- Windows: choco install ffmpeg (with Chocolatey) or download from gyan.dev/ffmpeg
- macOS: brew install ffmpeg
- Linux: sudo apt install ffmpeg (Ubuntu/Debian) or sudo dnf install ffmpeg (Fedora)

Setup

Clone the Repository

git clone https://github.com/easyhak/youtube-search-mcp.git
cd youtube-search-mcp

Install Dependencies Using uv (recommended):

uv sync

Using pip:

python -m venv .venv
# Activate the virtual environment
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
pip install -e ".[dev]"

Run the Server Using uv:

uv run python -m youtube_search_mcp.main

Or with activated virtual environment:

python -m youtube_search_mcp.main

Code Quality & Testing

Format Code: uv run black .
Lint Code: uv run ruff check .
Type Check: uv run mypy .
Run Tests: uv run pytest

🤝 Contributing

Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

Please refer to the Contributing Guidelines for more details.