Content
<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="/LICENSE"><img src="https://img.shields.io/github/license/easyhak/youtube-search-mcp?style=flat-square&color=blue" alt="License"></a>
<a href="https://github.com/easyhak/youtube-search-mcp/releases"><img src="https://img.shields.io/github/v/release/easyhak/youtube-search-mcp?style=flat-square&color=success" alt="Release"></a>
<a href="https://github.com/psf/black"><img src="https://img.shields.io/badge/code%20style-black-000000.svg?style=flat-square" alt="Code style: black"></a>
<a href="https://docs.astral.sh/ruff/"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json&style=flat-square" alt="Ruff"></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](https://docs.astral.sh/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](https://www.gyan.dev/ffmpeg/builds/)
- **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`:
```bash
# 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:
```bash
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`):
```json
{
"mcpServers": {
"youtube-search": {
"command": "youtube-search-mcp"
}
}
}
```
Or if using `uvx` (no installation required):
```json
{
"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](https://docs.astral.sh/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](https://www.gyan.dev/ffmpeg/builds/)
- **macOS**: `brew install ffmpeg`
- **Linux**: `sudo apt install ffmpeg` (Ubuntu/Debian) or `sudo dnf install ffmpeg` (Fedora)
### Setup
1. **Clone the Repository**
```bash
git clone https://github.com/easyhak/youtube-search-mcp.git
cd youtube-search-mcp
```
2. **Install Dependencies**
Using `uv` (recommended):
```bash
uv sync
```
Using `pip`:
```bash
python -m venv .venv
# Activate the virtual environment
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
pip install -e ".[dev]"
```
3. **Run the Server**
Using `uv`:
```bash
uv run python -m youtube_search_mcp.main
```
Or with activated virtual environment:
```bash
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**](https://github.com/easyhak/youtube-search-mcp/blob/main/CONTRIBUTING.md) for more details.
## 📜 License
Distributed under the MIT License. See [LICENSE](/LICENSE) for more information.
