Command Palette

Search for a command to run...

UnylyUnyly
Browse all

Youtube Search

FreeNot checked

A Model Context Protocol (MCP) server for searching and downloading YouTube videos without an API key. Powered by yt-dlp and FastMCP

GitHubEmbed

About

A Model Context Protocol (MCP) server for searching and downloading YouTube videos without an API key. Powered by yt-dlp and FastMCP

README

logo

YouTube Search & Download MCP Server

YouTube API 키 없이 동영상을 검색하고 다운로드하는 MCP 서버
Bug Report · Feature Request

License Release Code style: black Ruff

English · 한국어


🚀 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

  1. Clone the Repository

    git clone https://github.com/easyhak/youtube-search-mcp.git
    cd youtube-search-mcp
    
  2. 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]"
    
  3. 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.

📜 License

Distributed under the MIT License. See LICENSE for more information.

from github.com/easyhak/youtube-search-mcp

Install Youtube Search in Claude Desktop, Claude Code & Cursor

Recommended · one command, every IDE
unyly install youtube-search

Installs 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-mcp

Step-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

Compare 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