---

🚀 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.