内容
# youtube-tools-mcp
用于 YouTube 视频转录、清理、帧提取和视频/音频下载的 Python MCP 服务器。
## 概述
`youtube-tools-mcp` 是一个 Python MCP 服务器，帮助 AI 代理分析 YouTube 视频。它提供了以下工具：
- 提取 YouTube 视频转录/自动字幕，附带时间戳；
- 清理嘈杂的自动生成字幕；
- 在特定时间戳或间隔提取视频帧；
- 以保存的文件路径或内联图像数据返回帧；
- 读取本地图像文件作为 MCP 图像内容，供视觉模型使用；
- 以各种质量预设下载视频文件；
- 下载仅限音频的文件（mp3、m4a、opus、wav）；
- 为摘要、笔记和研究工作流程准备视频材料。
专为 Claude Code、VSCodium 和任何 MCP 兼容的代理设计。
## 工具
| 工具 | 描述 |
|---|---|
| `get_youtube_transcript` | 从 YouTube 视频中提取转录/字幕 |
| `get_youtube_video_metadata` | 获取视频标题、描述、频道 URL 和频道描述（如果可用） |
| `get_youtube_video_context` | 获取视频元数据和转录的 JSON 响应 |
| `clean_transcript` | 清理和格式化自动生成的转录文本 |
| `extract_video_frame` | 在特定时间戳提取单个帧 |
| `extract_video_frames` | 在指定时间戳提取多个帧 |
| `extract_frames_every` | 在固定间隔提取帧 |
| `read_image_file` | 读取本地图像路径并返回内联图像数据或视觉分析 |
| `analyze_image_file` | 使用配置的视觉模型分析本地图像 |
| `download_video` | 下载 YouTube 视频（最佳、720p、480p、360p） |
| `download_audio` | 下载仅限音频（mp3、m4a、opus、wav） |
| `list_playlist_videos` | 列出 YouTube 播放列表中的视频 |
| `list_channel_videos` | 列出 YouTube 频道的上传视频 |
| `list_channel_playlists` | 列出 YouTube 频道的播放列表 |
## 元数据和上下文
`get_youtube_video_metadata` 返回 JSON，包含：
- `title`
- `description`
- `channel_title`
- `channel_url`
- `channel_description`（如果可用）
- `duration`（秒）
- `upload_date`
在没有 `YOUTUBE_API_KEY` 的情况下，元数据通过 `yt-dlp` 获取。使用 `YOUTUBE_API_KEY` 时，通过 YouTube Data API 获取更丰富的频道描述，如果 API 恢复到 `yt-dlp`，响应中会包含一个 `warnings` 字段。
`get_youtube_video_context` 返回一个 JSON 对象，包含：
- `metadata`（与上述相同的字段）
- `transcript`（带时间戳的转录文本）
- `metadata_error`（仅当元数据获取失败但转录成功时）
这意味着 `get_youtube_video_context` 具有部分弹性：如果元数据无法获取，但转录仍然返回。
## 帧和图像模式
帧提取工具支持三种返回模式：
- `return_images=false`（默认）：将 JPEG 帧保存到磁盘并返回文件路径作为文本。与纯文本或非视觉模型一起使用。
- `return_images=true`：为视觉模型返回内联 MCP `ImageContent`。
- `vision_analysis=true`：将提取的帧发送到配置的 OpenAI 兼容视觉模型并返回文本描述。
帧参数：
| 参数 | 默认值 | 描述 |
|---|---|---|
| `output_dir` | 系统临时目录 | 保存帧时 `return_images=false` 的目录 |
| `max_width` | `null` | 可选的最大帧宽度。`null` 保留原始宽度 |
| `jpeg_quality` | `5` | ffmpeg JPEG 质量，`2` 为最佳，`31` 为最差 |
| `vision_prompt` | 默认图像描述提示 | `vision_analysis=true` 的可选提示 |
| `vision_model` | 配置的环境模型 | `vision_analysis=true` 的可选模型覆盖 |
| `download_first` | `"auto"` | 尝试直接流提取，首先然后回退到本地低分辨率源。使用 `true`/`"always"` 首先下载或 `false`/`"never"` 仅限直接流 |
帧提取解决了 `output_dir` 的绝对路径在 MCP 服务器进程内。如果传递相对目录，它将相对于 MCP 服务器的工作目录解析，该目录可能与代理工作区不同。工具响应包括解析的输出目录和相对路径解析使用的注释。
默认情况下，帧工具首先尝试直接 YouTube 流提取。如果失败，因为流无法获取或 ffmpeg 无法可靠地搜索/读取它，它们会下载低分辨率的本地回退源并重试。回退仍然为整个视频持续时间下载视频源，因此使用 `download_first=false` 或 `"never"` 当您想要避免任何本地视频下载。
`read_image_file(path)` 读取现有的本地 `.jpg`、`.jpeg`、`.png`、`.gif` 或 `.webp` 文件并返回它作为内联 MCP 图像内容。设置 `vision_analysis=true` 或调用 `analyze_image_file(path)` 以返回文本描述。支持 Unicode 路径，包括西里尔字母文件名和目录。
`vision_analysis=true` 不能与 `return_images=true` 组合。
**安全注意：** 视觉工具接受可选的每次调用 `vision_base_url` 和 `vision_api_key` 参数，因此您可以切换提供商而无需重新安装服务器。仅在一次性覆盖时使用这些；将 API 密钥传递到工具参数中可能会使它们留在 MCP 客户端日志中。对于常规使用，请首选环境变量（例如 `YOUTUBE_TOOLS_VISION_API_KEY`）设置在 MCP 客户端 `env` 块中。
对于非视觉模型，使用保存的路径或 `vision_analysis=true` 而不是直接读取图像文件。
## 安装
### 本地开发
```bash
git clone https://github.com/NewYaroslav/youtube-tools-mcp.git
cd youtube-tools-mcp
uv sync --extra dev
```
运行服务器：
```bash
uv run python -m youtube_tools_mcp.server
```
或直接运行：
```bash
py -X utf8 -m youtube_tools_mcp.server
```
### 通过 uvx（从 GitHub）
```bash
claude mcp add youtube-tools --scope user -- uvx --from git+https://github.com/NewYaroslav/youtube-tools-mcp youtube-tools-mcp
```
### 克劳德桌面配置
将以下内容添加到 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"youtube-tools": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/NewYaroslav/youtube-tools-mcp",
"youtube-tools-mcp"
]
}
}
}
```
### VSCodium / VS Code
将以下内容添加到 `.vscode/mcp.json`：
```json
{
"mcpServers": {
"youtube-tools": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/NewYaroslav/youtube-tools-mcp",
"youtube-tools-mcp"
]
}
},
"enabled": ["youtube-tools"]
}
```
### 为 MCP 客户端配置 API 密钥
核心工具无需 API 密钥即可工作。根据需要为要启用的功能添加环境变量：
- `YOUTUBE_API_KEY` 启用 YouTube Data API 功能，例如元数据和搜索。
- 视觉分析需要 `YOUTUBE_TOOLS_VISION_BASE_URL`、`YOUTUBE_TOOLS_VISION_API_KEY` 和 `YOUTUBE_TOOLS_VISION_MODEL`。
对于克劳德桌面、VS Code、VSCodium 和其他基于 JSON 的 MCP 客户端，在 `youtube-tools` 服务器条目中添加一个 `env` 块：
```json
{
"mcpServers": {
"youtube-tools": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/NewYaroslav/youtube-tools-mcp",
"youtube-tools-mcp"
],
"env": {
"YOUTUBE_API_KEY": "your-youtube-api-key",
"YOUTUBE_TOOLS_VISION_BASE_URL": "https://api.openai.com/v1",
"YOUTUBE_TOOLS_VISION_API_KEY": "your-vision-api-key",
"YOUTUBE_TOOLS_VISION_MODEL": "gpt-4o-mini",
"YOUTUBE_TOOLS_VISION_MAX_TOKENS": "1024"
}
}
}
}
```
删除未使用的功能的环境变量。不要提交实际的 API 密钥或令牌；使用用户级 MCP 配置或共享配置文件占位符。
使用克劳德 CLI，在 `--` 之前传递环境变量，然后传递服务器名称、命令和参数：
```bash
claude mcp add --scope user \
-e YOUTUBE_API_KEY=your-youtube-api-key \
-e YOUTUBE_TOOLS_VISION_BASE_URL=http://127.0.0.1:8000/v1 \
-e YOUTUBE_TOOLS_VISION_API_KEY=your-vision-api-key \
-e YOUTUBE_TOOLS_VISION_MODEL=your-vision-model \
-e YOUTUBE_TOOLS_VISION_MAX_TOKENS=1024 \
-- youtube-tools uvx --from git+https://github.com/NewYaroslav/youtube-tools-mcp youtube-tools-mcp
```
## 频道和播放列表列表
- `list_playlist_videos` 接受播放列表 URL 或原始播放列表 ID，并返回带有 `video_id`、`title`、`url`、`duration` 和 `position` 的 JSON 视频列表。
- `list_channel_videos` 接受频道 URL、句柄（`@name`）或原始频道 ID（`UC...`），并返回上传视频，格式相同。
- `list_channel_playlists` 接受频道 URL、句柄（`@name`）或原始频道 ID（`UC...`），需要 `YOUTUBE_API_KEY`。返回带有 `playlist_id`、`title`、`description` 和 `video_count` 的播放列表。
列表参数：
| 工具 | `max_results` 范围 | 默认值 |
|---|---|---|
| `list_playlist_videos` | 1..500 | 50 |
| `list_channel_videos` | 1..500 | 50 |
| `list_channel_playlists` | 1..50 | 50 |
`proxy`、`cookies_from_browser` 和 `client` 传递给 yt-dlp 与其他基于 yt-dlp 的工具相同。
注意：`list_playlist_videos` 和 `list_channel_videos` 的排序和完整性取决于 YouTube 页面结构和 yt-dlp 平面提取。
## 系统需求
- Python 3.12+
- **ffmpeg** - 帧提取和音频下载所需。转录、清理和视频下载工具无需它。
安装 ffmpeg：
| 平台 | 命令 |
|---|---|
| Windows | `winget install ffmpeg` 或 `choco install ffmpeg` |
| macOS | `brew install ffmpeg` |
| Linux | `sudo apt install ffmpeg` 或 `sudo dnf install ffmpeg` |
## 环境变量
环境变量可以在进程环境或本地 `.env` 文件中设置。`.env` 被 gitignore。
当通过 `uvx` 从 MCP 客户端安装时，服务器可能在您的项目检查之外运行。在这种情况下，在 MCP 客户端的 `env` 块或父进程环境中设置变量。
| 变量 | 必需 | 描述 |
|---|---|---|
| `YOUTUBE_API_KEY` | 否 | 启用 YouTube Data API 功能（元数据、搜索）。核心工具无需它。 |
| `HTTPS_PROXY` / `HTTP_PROXY` | 否 | 所有外出请求（转录、元数据、下载）的 HTTP/HTTPS 代理。按顺序检查：`HTTPS_PROXY`、`https_proxy`、`HTTP_PROXY`、`http_proxy`。 |
| `YOUTUBE_TOOLS_COOKIES_FROM_BROWSER` | 否 | `get_youtube_transcript` 的默认浏览器 cookie 源（如果工具调用未传递 `cookies_from_browser`）。示例：`firefox`。 |
| `YOUTUBE_TOOLS_TRANSCRIPT_API_REQUEST_TIMEOUT` | 否 | `youtube-transcript-api` 的每个请求的正有限 HTTP 超时秒。默认为 `5`。保持此值小有助于工具达到 yt-dlp/Data API 回退在 MCP 客户端级超时之前。 |
| `YOUTUBE_TOOLS_YTDLP_SOCKET_TIMEOUT` | 否 | yt-dlp 网络操作的正有限默认套接字超时秒。可以覆盖支持的工具上的 `ytdlp_socket_timeout`。 |
| `YOUTUBE_TOOLS_VISION_BASE_URL` | 视觉分析 | OpenAI 兼容的 base URL。回退到 `OPENAI_BASE_URL`，然后是 `ANTHROPIC_BASE_URL` + `/v1`。 |
| `YOUTUBE_TOOLS_VISION_API_KEY` | 视觉分析 | API 令牌。回退到 `OPENAI_API_KEY`。 |
| `YOUTUBE_TOOLS_VISION_MODEL` | 视觉分析 | 视觉能力模型。回退到 `OPENAI_VISION_MODEL`、`ANTHROPIC_TOOL_USE_MODEL`，然后 `ANTHROPIC_MODEL`。 |
| `YOUTUBE_OAUTH_CLIENT_ID` | 否 | 用于通过 YouTube Data API 字幕的 Google OAuth 客户端 ID。 |
| `YOUTUBE_OAUTH_CLIENT_SECRET` | 否 | 用于通过 YouTube Data API 字幕的 Google OAuth 客户端密钥。 |
| `YOUTUBE_TOOLS_VISION_MAX_TOKENS` | 否 | 视觉完成令牌预算。默认为 `1024`；值从 `64` 到 `4096` 限制。 |
| `YOUTUBE_TOOLS_VISION_TIMEOUT` | 否 | 视觉请求超时秒。默认为 `60`。
### 超时
有两个超时层：
1. **MCP 客户端调用超时** 由调用应用程序控制，而不是此服务器。例如，代理可能会在 90 秒后中止调用，即使服务器仍在工作。对于长视频/音频下载，请提高 MCP 客户端的调用超时或传递其调用级超时选项（如果客户端支持）。
2. **服务器端网络超时** 由此服务器控制。它们防止单个网络操作无限期挂起，可以按调用或环境变量设置。
超时值必须是正有限数字。无效值如 `0`、负数、`nan`、`inf` 或非数字字符串会被拒绝而不是被静默忽略。
支持的每次调用超时参数：
| 参数 | 工具 | 描述 |
|---|---|---|
| `transcript_api_timeout` | `get_youtube_transcript`、`get_youtube_video_context` | `youtube-transcript-api` 的每个请求 HTTP 超时。默认为 `YOUTUBE_TOOLS_TRANSCRIPT_API_REQUEST_TIMEOUT` 或 `5`。 |
| `ytdlp_socket_timeout` | `get_youtube_transcript`、`get_youtube_video_metadata`、`get_youtube_video_context`、`download_video`、`download_audio` | yt-dlp 网络操作的套接字超时。当省略时，默认为 `YOUTUBE_TOOLS_YTDLP_SOCKET_TIMEOUT`。 |
| `ffmpeg_timeout` | 帧提取工具 | 每个 ffmpeg 子进程的超时。 |
`ytdlp_socket_timeout` 不是总下载截止时间。大下载可以比此运行时间更长，只要 yt-dlp 保持套接字进度。通常这是您想要的：将 MCP 客户端的总调用超时设置足够高以适应预期文件大小，并使用 `ytdlp_socket_timeout` 失败的网络读取。
### 代理支持
所有网络工具支持可选的 HTTP/HTTPS 代理。您可以按两种方式设置：
1. **每次调用** - 在任何工具调用中直接传递 `proxy` 参数（例如 `proxy: "http://user:pass@host:8080"`）。这优先使用，并且适用于调用代理时很有用。
2. **环境变量** - 在 MCP 客户端 `env` 块中设置 `HTTPS_PROXY` 或 `HTTP_PROXY`。如果没有提供每次调用的代理，则自动应用。
设置代理后，它应用于：
- `youtube-transcript-api` 转录请求
- 通过 `urllib` 的 YouTube Data API 调用
- `yt-dlp` 视频/音频下载和元数据获取
将代理添加到您的 MCP 客户端 `env` 块：
```json
{
"mcpServers": {
"youtube-tools": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/NewYaroslav/youtube-tools-mcp",
"youtube-tools-mcp"
],
"env": {
"HTTPS_PROXY": "http://proxy.example.com:8080"
}
}
}
``` ### OAuth 回退转录（仅限您自己的视频）
当 `youtube-transcript-api` 因 IP 块而失败时，服务器可以回退到 YouTube Data API `captions.download`，这需要 OAuth 2.0 授权。您拥有的视频）
当 `youtube-transcript-api` 因为 IP 块而失败时，服务器可以回退到 YouTube Data API `captions.download`，这需要 OAuth 0 授权。
> **重要限制：** `captions.download` 通过 YouTube Data API **仅适用于您自己的视频**（您拥有或管理的频道中的视频）。对于第三方公共视频，此回退将返回 `403 Forbidden`。对于第三方视频，请改用 `cookies_from_browser`（参见下文）。
**前提：
1. 前往 [Google Cloud Console](https://console.cloud.google.com/) 并创建或选择一个项目。
2. 启用 **YouTube Data API v3**。
3. 前往 **APIs & Services > Credentials > Create Credentials > OAuth client ID**。
4. 选择 **Web application** 作为应用程序类型。
5. 命名它（例如 `youtube-tools-mcp-web`）。
6. 在 **Authorized redirect URIs** 下点击 **Add URI** 并输入：
```
http://127.0.0.1:8085
```
7. 点击 **Create** 并记下 **Client ID** 和 **Client Secret**。
**仅需授权一次：
如果在本地运行（项目检出）：
```bash
# PowerShell
$env:YOUTUBE_OAUTH_CLIENT_ID="your-client-id.apps.googleusercontent.com"
$env:YOUTUBE_OAUTH_CLIENT_SECRET="your-client-secret"
uv run youtube-tools-mcp-oauth
```
```bash
# Bash / Linux / macOS
export YOUTUBE_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com
export YOUTUBE_OAUTH_CLIENT_SECRET=your-client-secret
uv run youtube-tools-mcp-oauth
```
### 如果通过 `uvx` 从 MCP 客户端运行：
在 MCP 客户端的 `env` 块中设置 `YOUTUBE_OAUTH_CLIENT_ID` 和 `YOUTUBE_OAUTH_CLIENT_SECRET`，然后从具有相同 `uvx` 环境的终端运行 CLI：
```bash
uvx --from git+https://github.com/NewYaroslav/youtube-tools-mcp youtube-tools-mcp-oauth
```
令牌文件存储在服务器运行的机器上。对于远程或容器化的 MCP 客户端，请将 `~/.config/youtube-tools-mcp/oauth.json` 挂载或同步到容器中。
### 工作原理：
- `get_youtube_transcript` 首先尝试 `youtube-transcript-api`。
- 如果请求被阻止 (`RequestBlocked`)，它会回退到 `captions.download` 通过 YouTube Data API。
- 在每次调用之前，OAuth 令牌会自动刷新；您不需要重新授权，除非令牌被撤销。
- `YOUTUBE_API_KEY` 仍然推荐使用，因为它启用 `captions.list`（不需要 OAuth），但 OAuth 处理实际下载。
**安全注意：** OAuth 令牌存储在本地 JSON 中。在 Linux/macOS 上，文件以 `0600` 权限创建。在 Windows 上，文件权限取决于您的用户配置文件。请保持令牌文件私有。如果需要，请在 [Google Account Permissions](https://myaccount.google.com/permissions) 中撤销令牌。
### 浏览器Cookie用于YouTube身份验证
几个工具接受一个`cookies_from_browser`参数，该参数告诉`yt-dlp`从本地浏览器配置文件中读取Cookie。当YouTube返回机器人检查、验证码或登录墙时，这非常有用。
支持的值包括任何`yt-dlp`浏览器语法，例如：
- `"chrome"`，`"firefox"`，`"edge"`，`"safari"`
- `"chrome:Profile 1"`用于特定配置文件
对于转录提取，您可以在MCP客户端配置文件中设置Cookie为默认值：
```json
{
"mcpServers": {
"youtube-tools": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/NewYaroslav/youtube-tools-mcp",
"youtube-tools-mcp"
],
"env": {
"YOUTUBE_TOOLS_COOKIES_FROM_BROWSER": "firefox"
}
}
}
}
```
当设置此默认值时，`get_youtube_transcript`首先尝试`yt-dlp`字幕路径，而不是等待`youtube-transcript-api`失败后才回退。这样有助于避免MCP客户端调用超时，当YouTube反复阻止未经身份验证的转录请求时。
当未设置浏览器Cookie默认值时，`get_youtube_transcript`仍然对`youtube-transcript-api`发出的每个单独的HTTP请求应用`YOUTUBE_TOOLS_TRANSCRIPT_API_REQUEST_TIMEOUT`（默认值：`5`秒），然后可以继续使用`yt-dlp`字幕回退。
传递一个显式的空白`cookies_from_browser`值以禁用单个调用的环境默认值。
**安全注意：** `cookies_from_browser`指示`yt-dlp`从您的本地机器读取已验证的Cookie。仅在您拥有的浏览器配置文件且值得信赖的机器上使用它。永远不要将其指向您不控制的浏览器配置文件。
### 如果您在没有令牌的情况下安装了MCP服务器
更新现有的`youtube-tools` MCP服务器条目，添加所需的`env`变量，并完全重启MCP客户端。
对于Claude Desktop，VS Code和VSCodium，编辑现有的JSON配置文件条目。对于Claude CLI，删除并重新添加具有所需环境的服务器，或编辑生成的MCP配置文件（如果您的客户端支持它）。
更新令牌后：
1. 完全重启MCP客户端。
2. 确认`youtube-tools`服务器重新连接。
3. 重试需要令牌的工具。
## 开发
```bash
uv sync --extra dev
uv run ruff check .
uv run ruff format .
uv run pytest
```
### 用于开发测试的本地`.mcp.json`
在项目根目录中创建`.mcp.json`（被git忽略），以便在其他MCP工具旁边本地运行服务器：
对于本地开发，您也可以将这些值放在项目根目录的`.env`文件中。当您希望MCP客户端配置自包含时，请使用`env`块。
```json
{
"mcpServers": {
"youtube-tools": {
"command": "uv",
"args": ["run", "python", "-m", "youtube_tools_mcp.server"],
"env": {
"YOUTUBE_API_KEY": "您的YouTube API密钥",
"YOUTUBE_TOOLS_VISION_BASE_URL": "https://api.openai.com/v1",
"YOUTUBE_TOOLS_VISION_API_KEY": "您的视觉API密钥",
"YOUTUBE_TOOLS_VISION_MODEL": "gpt-4o-mini",
"YOUTUBE_TOOLS_VISION_MAX_TOKENS": "1024"
}
},
"context7": {
"command": "npx",
"args": ["-y", "@upstash/context7-mcp@latest"]
},
"fetch": {
"command": "uvx",
"args": ["mcp-server-fetch"]
}
}
}
```
## 许可证
MIT
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器