内容
# youtube-mcp
YouTube 的 MCP 服务器。为任何 MCP 客户端（例如 Claude Desktop）提供四种工具：
| 工具 | 功能 |
|---|---|
| `get_video` | 获取视频元数据（标题、浏览量、时长等） |
| `get_transcript` | 获取带时间戳的的字幕片段（YouTube 字幕） |
| `search_videos` | 按关键词搜索 YouTube 视频，按日期或相关性排序 |
| `transcribe_video` | 下载音频并使用 Whisper 在本地转录 - 适用于没有字幕的情况，无需额外的 API 密钥 |
> **零系统依赖。** `ffmpeg` 通过 `static-ffmpeg` 捆绑并在首次使用时自动下载。无需 Homebrew，无需手动安装。
## 设置
### 1. 获取 YouTube Data API v3 密钥
1. 前往 [console.cloud.google.com](https://console.cloud.google.com)
2. 创建项目 → **APIs & Services → 启用 API** → 搜索 "YouTube Data API v3" → 启用
3. **APIs & Services → 凭证 → 创建凭证 → API 密钥**
4. 复制密钥
### 2. 安装
```bash
git clone https://github.com/sparsh-gaurav/youtube-mcp.git
cd youtube-mcp
pip install -e ".[dev]"
```
### 3. 配置
```bash
cp .env.example .env
# 编辑 .env 并粘贴您的 YOUTUBE_API_KEY
```
### 4. 运行测试
```bash
pytest -v
```
### 5. 连接 Claude Desktop
添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"youtube": {
"command": "/path/to/youtube-mcp/.venv/bin/python3",
"args": ["-m", "youtube_mcp.server"],
"cwd": "/path/to/youtube-mcp",
"env": {
"YOUTUBE_API_KEY": "your_key_here"
}
}
}
}
```
重启 Claude Desktop。然后，您可以询问类似的问题：
> "搜索关于 Ram Mandir fund scam 的最新 YouTube 视频并总结它们"
> "获取视频 dQw4w9WgXcQ 的字幕"
> "转录这个视频，即使它没有字幕：..."
> "这个 YouTube 视频的浏览量和时长是多少？"
## 首次运行说明
- **`transcribe_video` 首次调用**：下载 Whisper `base` 模型（约 145 MB）到 `~/.cache/whisper`，并将捆绑的 `ffmpeg` 二进制文件（约 60 MB）下载到 Python 包目录。两者都经过缓存 - 随后的调用速度很快。
- **临时文件**：转录期间下载的音频存储在系统临时目录中，并在每次调用后自动删除，无论调用是否成功。
## 工具
### `get_video(video_id: str) -> VideoMetadata`
| 字段 | 类型 | 描述 |
|---|---|---|
| `id` | str | YouTube 视频 ID |
| `title` | str | 视频标题 |
| `description` | str | 完整描述 |
| `channel_title` | str | 频道名称 |
| `view_count` | int | 总浏览量 |
| `like_count` | int \| None | 点赞数（如果被创作者隐藏，则为 None） |
| `duration` | str | ISO 8601 时长（例如 `PT3M33S`） |
| `published_at` | str | ISO 8601 发布时间 |
| `thumbnail_url` | str | 默认缩略图 URL |
---
### `get_transcript(video_id: str, language: str | None = None) -> list[TranscriptSegment]`
在可用时返回 YouTube 的字幕片段。
| 字段 | 类型 | 描述 |
|---|---|---|
| `start` | float | 片段开始时间（秒） |
| `duration` | float | 片段时长（秒） |
| `text` | str | 字幕文本 |
`language`：BCP-47 代码（例如 `"en"`、`"hi"`）。默认为第一个可用语言。
---
### `search_videos(query: str, max_results: int = 5, language: str | None = None, order: str = "date") -> list[VideoSearchResult]`
通过 Data API v3 搜索 YouTube。默认按最新排序。
| 字段 | 类型 | 描述 |
|---|---|---|
| `video_id` | str | YouTube 视频 ID |
| `title` | str | 视频标题 |
| `description` | str | 摘要描述 |
| `channel_title` | str | 频道名称 |
| `published_at` | str | ISO 8601 发布时间 |
| `thumbnail_url` | str | 默认缩略图 URL |
`max_results`：1-50，默认为 5。
`order`：`date`（默认）、`relevance`、`viewCount`、`rating`。
`language`：BCP-47 相关性提示（例如 `"en"`、`"hi"`）。可选。
---
### `transcribe_video(video_id: str, language: str | None = None) -> WhisperTranscript`
下载音频并使用 OpenAI Whisper（`base` 模型）在本地转录。无需 API 密钥。
| 字段 | 类型 | 描述 |
|---|---|---|
| `video_id` | str | YouTube 视频 ID |
| `text` | str | 完整转录文本 |
| `segments` | list[WhisperSegment] | 带时间戳的片段 |
每个 `WhisperSegment`：
| 字段 | 类型 | 描述 |
|---|---|---|
| `start` | float | 片段开始时间（秒） |
| `end` | float | 片段结束时间（秒） |
| `text` | str | 转录文本 |
`language`：Whisper 的 BCP-47 提示（例如 `"en"`、`"hi"`）。如果省略，则自动检测。
---
## 项目结构
```
src/youtube_mcp/
server.py # MCP 入口点，工具注册
api.py # YouTube Data API v3 包装器（get_video, search_videos）
transcript.py # youtube-transcript-api 包装器（get_transcript）
whisper.py # yt-dlp + 本地 Whisper 转录器（transcribe_video）
models.py # Pydantic 模型
tests/
test_api.py
test_transcript.py
test_whisper.py
```
