Youtube Search
FreeNot checkedA Model Context Protocol (MCP) server for searching and downloading YouTube videos without an API key. Powered by yt-dlp and FastMCP
About
A Model Context Protocol (MCP) server for searching and downloading YouTube videos without an API key. Powered by yt-dlp and FastMCP
README
YouTube Search & Download MCP Server
YouTube API 키 없이 동영상을 검색하고 다운로드하는 MCP 서버
Bug Report
·
Feature Request
🚀 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
uvorpip. 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) orsudo dnf install ffmpeg(Fedora)
- Windows:
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) orsudo dnf install ffmpeg(Fedora)
- Windows:
Setup
Clone the Repository
git clone https://github.com/easyhak/youtube-search-mcp.git cd youtube-search-mcpInstall Dependencies Using
uv(recommended):uv syncUsing
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.mainOr 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.
📜 License
Distributed under the MIT License. See LICENSE for more information.
Install Youtube Search in Claude Desktop, Claude Code & Cursor
unyly install youtube-searchInstalls into Claude Desktop, Claude Code, Cursor & VS Code — handles npx, uvx and build-from-source repos for you.
First time? Get the CLI: curl -fsSL https://unyly.org/install | sh
Or configure manually
Run in your terminal:
claude mcp add youtube-search -- uvx youtube-search-mcpStep-by-step: how to install Youtube Search
FAQ
Is Youtube Search MCP free?
Yes, Youtube Search MCP is free — one-click install via Unyly at no cost.
Does Youtube Search need an API key?
No, Youtube Search runs without API keys or environment variables.
Is Youtube Search hosted or self-hosted?
Self-hosted: the server runs locally on your machine via the install command above.
How do I install Youtube Search in Claude Desktop, Claude Code or Cursor?
Open Youtube Search on unyly.org, pick your client tab (Claude Desktop, Claude Code, Cursor) and press Install — the config is generated automatically, no JSON editing.
Related MCPs
ARA
Generate images, video and audio from any AI agent — one connector.
by ARAVideo Analyzer
MCP server for video analysis — extracts transcripts, key frames with OCR, and annotated timelines from video URLs. Supports Loom and direct video files (.mp4,
by guimatheus92Omni Video
An MCP server that transforms LLM-enabled IDEs into professional video editors by pre-processing footage into text proxies, generating motion graphics via HTML/
by buildwithtazaYouTube
Transcripts, channel stats, search
by YouTubeEverArt
AI image generation using various models.
by modelcontextprotocolgpu-bridge/mcp-server
GPU inference API for LLMs, image and video generation, TTS, Whisper, embeddings, reranking and OCR, paid per use via x402 or an API key.
by gpu-bridgemerterbak/Grok-MCP
Access xAI's Grok API with agentic tool calling, image generation, vision and file support.
by merterbakSureScaleAI/openai-gpt-image-mcp
Image generation and editing with OpenAI's GPT image models.
by SureScaleAIYangLiangwei/PersonalizationMCP
Aggregate personal data from Steam, YouTube, Bilibili, Spotify, Reddit and other gaming, music, video and social platforms, with OAuth2 and token management.
by YangLiangweiAceDataCloud/MCPFlux
Flux image generation and editing from Black Forest Labs via the Ace Data Cloud API.
by AceDataCloudCompare Youtube Search with
Not sure what to pick?
Find your stack in 60 seconds
Author?
Embed badge for your README
Browse similar
All media MCPs
