内容
<div align="center">
<img width="400" alt="logo" src="https://github.com/user-attachments/assets/4ab98cc2-d0f7-4953-840f-d7fb43d4b893" />
<h1 align="center">YouTube 搜索与下载 MCP 服务器</h1>
<p align="center">
<strong>无需 YouTube API 密钥的视频搜索与下载 MCP 服务器</strong>
<br />
<a href="https://github.com/easyhak/youtube-search-mcp/issues/new/choose">报告 Bug</a>
·
<a href="https://github.com/easyhak/youtube-search-mcp/issues/new/choose">功能请求</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="许可证"></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="发布版本"></a>
<a href="https://github.com/psf/black"><img src="https://img.shields.io/badge/code%20style-black-000000.svg?style=flat-square" alt="代码风格：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>
---
## 🚀 YouTube 搜索 MCP 是什么？
这是一个生产级别的 **Model Context Protocol (MCP)** 服务器，允许您在无需 YouTube API 密钥的情况下搜索、获取信息和下载 YouTube 视频和音频。它旨在与 MCP 客户端（如 Claude Desktop 和 Cursor）无缝协作。
服务器使用 `/` 进行稳健的后端操作，使用 `FastMCP` 进行高性能服务器框架。
## ✨ 主要功能
- **无需 API 密钥**：使用 `yt-dlp` 自由搜索和下载。
- **轻松安装**：使用 `uv` 或 `pip` 进行简单设置。与 MCP 客户端无缝协作。
- **视频和音频下载**：以各种格式（`mp4`、`mkv`、`mp3`、`wav` 等）和质量下载内容。
- **播放列表支持**：搜索播放列表，获取播放列表详细信息，并从任何播放列表中检索所有视频。
- **丰富的元数据**：获取详细的视频信息，包括时长、观看次数和章节。
- **客户端兼容性**：与 Claude、Cursor 和其他 MCP 兼容的客户端配合良好。
- **稳健且类型安全**：在 SOLID 架构上构建，具有使用 Pydantic 的完全类型安全。
## 🏁 入门指南（适用于用户）
### 先决条件
- Python 3.10 或更高版本
- [uv](https://docs.astral.sh/uv/) （推荐）或 `pip`
- **FFmpeg** （必须安装并在您的系统 PATH 中可用）
- **Windows**：`choco install ffmpeg` （使用 Chocolatey）或从 [gyan.dev/ffmpeg](https://www.gyan.dev/ffmpeg/builds/) 下载
- **macOS**：`brew install ffmpeg`
- **Linux**：`sudo apt install ffmpeg` （Ubuntu/Debian）或 `sudo dnf install ffmpeg` （Fedora）
### 安装
使用 `uv` （推荐）或 `pip` 安装软件包：
```bash
# 使用 uv（推荐）
uv pip install youtube-search-mcp
# 或使用 pip
pip install youtube-search-mcp
```
### 运行服务器
安装后，您可以直接运行服务器：
```bash
youtube-search-mcp
```
## 💻 客户端配置
配置您的 MCP 客户端以连接到服务器。
**适用于 Claude Desktop 或 Cursor：**
将以下内容添加到您的 MCP 客户端配置中（通常为 `claude_desktop_config.json` ）：
```json
{
"mcpServers": {
"youtube-search": {
"command": "youtube-search-mcp"
}
}
}
```
或如果使用 `uvx` （无需安装）：
```json
{
"mcpServers": {
"youtube-search": {
"command": "uvx",
"args": ["youtube-search-mcp"]
}
}
}
```
## 🔧 配置
您可以通过设置环境变量来自定义服务器的行为。这些变量可以添加到您的 MCP 客户端配置中（例如 `claude_desktop_config.json` ）或通过在项目根目录中设置 `.env` 文件。
| 变量 | 描述 | 默认值 |
|----------|-------------|---------|
| `YT_MCP_DOWNLOAD_DIR` | 视频/音频保存的目录 | `downloads` |
| `YT_MCP_DEFAULT_VIDEO_QUALITY` | 默认视频质量（`best`、`high`、`medium`、`low`） | `best` |
| `YT_MCP_DEFAULT_MAX_RESULTS` | 默认返回的搜索结果数量 | `10` |
| `YT_MCP_LOG_LEVEL` | 日志级别（`DEBUG`、`INFO`、`WARNING`、`ERROR`） | `INFO` |
---
## 🛠️ 适用于开发者和贡献者
有兴趣贡献吗？以下是如何设置您的开发环境。
### 先决条件
- Git
- Python 3.10+
- [uv](https://docs.astral.sh/uv/) （推荐）或 `pip`
- **FFmpeg** （必须安装并在您的系统 PATH 中可用以进行开发）
- **Windows**：`choco install ffmpeg` （使用 Chocolatey）或从 [gyan.dev/ffmpeg](https://www.gyan.dev/ffmpeg/builds/) 下载
- **macOS**：`brew install ffmpeg`
- **Linux**：`sudo apt install ffmpeg` （Ubuntu/Debian）或 `sudo dnf install ffmpeg` （Fedora）
### 设置
1. **克隆仓库**
```bash
git clone https://github.com/easyhak/youtube-search-mcp.git
cd youtube-search-mcp
```
2. **安装依赖项**
使用 `uv` （推荐）：
```bash
uv sync
```
使用 `pip`：
```bash
python -m venv .venv
# 激活虚拟环境
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
pip install -e ".[dev]"
```
3. **运行服务器**
使用 `uv`：
```bash
uv run python -m youtube_search_mcp.main
```
或使用已激活的虚拟环境：
```bash
python -m youtube_search_mcp.main
```
### 代码质量和测试
- **格式化代码**：`uv run black .`
- **检查代码**：`uv run ruff check .`
- **类型检查**：`uv run mypy .`
- **运行测试**：`uv run pytest`
## 🤝 贡献
贡献使开源社区成为一个令人惊叹的地方，学习、启发和创造。您所做的任何贡献都 **非常感谢**。
请参阅 [**贡献指南**](https://github.com/easyhak/youtube-search-mcp/blob/main/CONTRIBUTING.md) 以获取更多详细信息。
## 📜 许可证
在 MIT 许可证下分发。有关更多信息，请参见 [LICENSE](/LICENSE)。
