YTDL RMCP

ytdl-rmcp

通过 MCP 和 CLI 实现 yt-dlp 搜索、下载、元数据处理、交付和 Plex 工作流。

使用 Rust 和 rmcp crate 编写。首次运行时会自动下载 yt-dlp 和 ffmpeg 到每位用户专属的缓存中，因此宿主无需预先安装它们——安装只需这一个二进制文件。

**30 秒上手：**运行 npx -y @dinglebear/rytdl setup -> 配置目标路径 -> 调用 youtube_search 或 youtube_probe；只有在明确目标位置和信任边界后，才使用 youtube_download。

**状态：**面向个人媒体的生产级 MCP 服务。只读的搜索、探测和统计路径是安全的；下载、播放列表、队列排空和标签写入路径会创建或 移动状态，适用于受信任的调用方。

**不适用于：**通用网络下载 SaaS、多租户媒体导入边界、替代 yt-dlp 上游网站处理机制，或供不受信任的 MCP 调用方任意写入文件系统。

目录

• 命名
• 功能与边界
• 安装
• 快速入门
• 客户端配置
• 运行时接口
• MCP 工具参考
• CLI 参考
• 配置
• 身份验证
• 安全与信任模型
• 架构
• 分发约定
• 开发
• 验证
• 部署
• 故障排除
• 相关服务
• 文档
• 许可证

命名

接口	本仓库
仓库	dinglebear-ai/rytdl
Cargo crate	ytdl-rmcp
npm 包	@dinglebear/rytdl
CLI / 二进制文件	rytdl
MCP 工具	youtube_search、youtube_search_ui、youtube_download、youtube_probe、youtube_identify、youtube_stats、youtube_plex_playlist、youtube_transfer_queue
环境变量前缀	YTDLP_*，以及 FFMPEG_*、FPCALC_PATH 和 YTDLP_LOG
传输方式	仅 stdio——无 HTTP 监听器，无服务端口

crate 和 npm 包采用 *-rmcp 系列命名模式，而仓库和运行时二进制文件命名为 rytdl，让本地 shell 使用简短的 Rust 原生命令。

功能与边界

• 通过 yt-dlp 搜索 YouTube，不下载媒体。
• 将音频、视频或两者下载到暂存目录，为音频添加元数据标签，并将结果传输到本地、SSH 或 rclone 目标位置。
• 可选地通过 AcoustID/MusicBrainz 为音频生成指纹，并将已完成的音频下载同步到 Plex 播放列表。
• 根据成功传输历史创建 Plex 播放列表，并排空由服务端生成、保留暂存数据的传输清单。
• 为能够渲染嵌入式小组件的宿主提供 MCP App 搜索界面。
• 使用 JSONL 台账支持可重复安全的下载和统计。

本仓库负责	上游负责	明确不在范围内
MCP 工具、CLI 设置、媒体暂存、标签写入、传输策略、队列清单、配置验证、响应构造、插件/包元数据。	yt-dlp 提取行为、源网站可用性、ffmpeg 媒体转换、Plex 媒体库索引、SSH/rclone 身份验证。	多租户隔离、供不受信任的调用方任意写入本地文件、凭据代理、针对特定网站的抓取保证、替代媒体服务器。

---

功能

• 音频、视频或两者兼有——默认以音频为主，并分别提供音频和视频目标。
• 完善的标签——嵌入标题／艺术家／专辑／日期和封面图，并将输出整理为 Artist/Title [id].ext，方便媒体服务器（Plex 等）准确编入索引。采用非贪婪的 Artist - Title 解析方式，从自由格式的视频标题中提取艺术家。源 .info.json、缩略图和描述等附属文件会与媒体文件一同保留，以便日后重新标记或编入索引。默认会从嵌入的标题元数据中去除常见的 YouTube 标题杂项，例如 (Official Video)、[Official Audio] 和末尾的频道账号名。
• 独立的路径处理——直接运行二进制文件时，它会下载／缓存 yt-dlp 和 ffmpeg；容器镜像则预装了 ffmpeg、fpcalc、SSH 和 rsync，适用于媒体主机上的批量任务。
• 自动安装——ytdl-rmcp setup 会通过各工具自带的 mcp add，将服务注册到 Claude Code、Codex 和／或 Gemini CLI。
• 可靠的传输——本地路径（/path）由二进制文件自身在进程内复制；SSH 目标（host:/path）使用 rsync -a --partial --protect-args，若缺少 rsync 则回退到 scp；rclone 目标（remote:path 或 rclone:remote:/path）则使用 rclone copy。传输失败时，本地暂存副本会保留以供重试，并记录为可清空的清单，供 youtube_transfer_queue 使用。
• 可安全重复运行——use_archive 会按模式记录已下载的 ID，并在后续运行时跳过这些内容；YouTube 混音／电台 URL 会自动清理为种子视频。
• 支持统计的账本——每次下载调用完成后，都会追加一条 JSONL 记录，包含时间戳、目标位置、文件、字节数、上传者和传输状态。
• Plex 播放列表同步——配置好 Plex 凭据后，下载的音频默认会添加到 yt-dlp Downloads。

MCP 工具参考

工具	用途
youtube_search	使用 yt-dlp 搜索 YouTube，并返回结果 URL，不下载内容。
youtube_search_ui	在支持 MCP App 的宿主中打开交互式 YouTube 搜索界面。
youtube_download	下载一个或多个 URL（音频／视频／两者兼有），并传输到目标路径。
youtube_probe	只读：解析标题／时长／上传者／格式数量，不下载内容。
youtube_identify	使用 fpcalc 对本地音频进行指纹识别，返回 AcoustID/MusicBrainz 候选结果，预览规范标签，并可选择写入高置信度标签。
youtube_stats	汇总下载账本：总数、文件类型、上传者和近期记录。
youtube_plex_playlist	根据成功传输的音频历史记录，创建或预览 Plex 音频播放列表。
youtube_transfer_queue	列出并清空保留的暂存传输失败清单。

youtube_download 参数

参数	默认值	含义
urls	—（必填）	一个 URL 字符串或 URL 数组。
mode	audio	audio、video 或 both。
audio_format	env YTDLP_AUDIO_FORMAT → mp3	mp3/m4a/opus/flac/wav/best。
audio_quality	0	有损编解码器的 yt-dlp 音质：0–9 或类似 192K 的比特率。
max_height	best	视频分辨率上限（例如 1080）。
container	mp4	视频容器，可选 mp4 或 mkv。
target_path	env YTDLP_TARGET_PATH	音频的目标位置。本地路径使用 /path，SSH 使用 host:/path，rclone 使用 remote:path 或 rclone:remote:/path。
video_target_path	env YTDLP_VIDEO_TARGET_PATH → target_path	当视频需要存放在与音频不同的位置时，指定视频的目标位置。支持相同的目标格式。
keep_local	false	传输后保留本地暂存副本。
use_archive	false	记录并跳过已下载的 ID（按模式分别记录）。
plex_playlist	env YTDLP_PLEX_PLAYLIST → 配置 Plex 时为 yt-dlp Downloads	用于添加已下载音轨的 Plex 播放列表标题或 ID。需要 YTDLP_PLEX_URL 和 YTDLP_PLEX_TOKEN。
response_format	markdown	markdown 或 json。

配置 Plex 凭据后，成功下载并生成音频文件时，系统会在 Plex 中搜索每首已下载曲目，在需要时创建目标播放列表，并添加尚未存在的曲目，同时跳过已有曲目。默认播放列表为 yt-dlp Downloads；设置 YTDLP_PLEX_PLAYLIST 或传入 plex_playlist 可覆盖该值。Plex 错误会通过 plex_playlist_error 报告，但不会导致已完成的下载失败。JSON 响应包含 plex_playlist 摘要，其中列出 matched、added、already_present 和 missing 计数。

通过 MusicBrainz/AcoustID 进行规范元数据匹配的说明见 docs/musicbrainz-acoustid.md。配置 YTDLP_ACOUSTID_CLIENT_KEY 后，youtube_download 会自动对已下载的音频执行高置信度 MusicBrainz 重新标记；youtube_identify 仍可用于预览或修复现有媒体库文件，并可通过 write_tags=true 启用手动标签写入。

youtube_download JSON 响应

使用 response_format=json 时，调用会返回一个描述该批次的对象：

字段	含义
transferred	如果所有生成的子目录都已到达目标位置，则为 true。
transfer_error	成功时为 null，否则为失败或超时消息（字符串）。
target_path / destination / destinations	实际使用的各类型目标位置。
staging_kept_at	保留以供重试的本地暂存路径（传输失败或请求了 keep_local 时设置）。
total_files / total_bytes / total_size	所有项目的汇总计数。
partial_items	出错但仍生成了文件的项目数。
failed_items	出错且未生成任何文件的项目数。
items[]	每个 URL 的结果，分别包含 status、title、video_id、error 和 files[] 列表。

每个 items[].status 的值为：

• ok — 已成功并生成文件。
• partial — 发生错误，但仍生成了部分文件。
• failed — 出错且未生成任何文件。
• skipped — 没有新内容（已在存档中）。

仅当运行了相关阶段时，才会附加可选键：

• metadata_retag — MusicBrainz/AcoustID 自动重新标记摘要（attempted、matched、written、skipped、errors，或 error 字符串）；配置 YTDLP_ACOUSTID_CLIENT_KEY 时会提供此字段。
• plex_playlist — Plex 播放列表摘要（playlist、matched、added、already_present、missing）；如果 Plex 更新失败，则改为设置 plex_playlist_error（Plex 故障不会导致下载失败）。
• history_error — 下载成功但 JSONL 账本追加失败时设置。

youtube_probe 接受 urls 和 response_format。

youtube_plex_playlist

根据成功的 ytdl-rmcp 下载历史，创建或预览 Plex 音频播放列表。

操作：

操作	含义
list_candidates	返回历史记录中 transferred 为 true 的音频候选项。
preview	在不修改 Plex 的情况下，将所选候选项与 Plex 匹配。
apply	将所选候选项幂等地添加到 Plex 音频播放列表。

候选项源自历史记录，且仅限音频。失败或暂存目录保留的传输会被排除。

apply 可返回 plexamp_url、plex_web_url 和 playback_link_status。plexamp_url 是尽力生成的 listen.plex.tv 播放链接，并非 Plexamp 官方 API 的保证。常规 Plex 播放列表 API 调用使用官方 Plex Media Server API。

youtube_transfer_queue

列出并清空由服务端创建的传输失败清单。

操作：

操作	含义
list	显示待处理且保留暂存目录的传输清单。
retry	通过不透明的 manifest_id 重试一份清单。
retry_all	重试所有待处理清单。
prune	删除暂存目录已不存在的清单。

队列不会接受任意文件系统路径。重试时会使用失败时记录的原始目标路径，并在传输前重新检查本地目标策略。只有在暂存目录、清单 ID、文件列表和原始目标均保持匹配时，本地服务端才会创建清单。

youtube_identify 参数

参数	默认值	含义
paths	—（必填）	一个本地音频文件路径字符串，或路径数组。
write_tags	false	将高置信度的 MusicBrainz 标签预览写回音频文件。
response_format	markdown	markdown 或 json。

youtube_identify 会运行 Chromaprint fpcalc，将指纹发送到 AcoustID，并返回 MusicBrainz 录音候选项。最佳候选项达到高置信度时，它还会获取 MusicBrainz 录音/发行数据，并附带 retag_preview，展示规范艺人、标题、发行名称、发行日期、发行类型、曲目编号和 MusicBrainz ID。默认情况下，此操作仅用于预览。设置 write_tags=true 后，它会使用 Lofty 将预览写入文件，包括常见的标题/艺人/专辑/日期/曲目字段，以及 MusicBrainz 录音、发行、发行组和发行类型标签。此功能需要 YTDLP_ACOUSTID_CLIENT_KEY；如果 fpcalc 不在 PATH 中，请设置 FPCALC_PATH。

youtube_search 参数

参数	默认值	含义
query	-（必填）	YouTube 搜索文本。服务端会将其传递给 yt-dlp，格式为 ytsearchN:<query>。
limit	10	结果数量，限制在 1..=25 范围内。
response_format	markdown	markdown 或 json。

youtube_search_ui 接受相同的输入并返回相同的搜索数据，此外还会提供 MCP App 元数据，供能够呈现嵌入式 UI 的宿主使用。不支持应用呈现的宿主仍会收到常规搜索结果文本和结构化数据。

MCP App 模式

youtube_search_ui 是此仓库中由 widget 支持的入口：

• 工具描述符会公布 _meta.ui.resourceUri。
• 服务端通过 resources/list 和 resources/read 提供 ui://ytdl-rmcp/youtube-search.html。
• 该资源使用 text/html;profile=mcp-app，并带有明确的 CSP 元数据块。
• .mcpb / .dxt 打包会安装本地服务端；UI 资源仍通过 MCP 工具/资源协议公布，并由宿主呈现。

youtube_stats 参数

参数	默认值	含义
limit	10	包含的近期账本条目数，限制在 0..=100 范围内。
response_format	markdown	markdown 或 json。

JSON 统计数据包括 total_downloads、total_files、total_bytes、 skipped_entries、by_kind、by_uploader 和 recent。分组字段包括 downloads（兼容性别名，表示调用次数）、calls、items、files、 bytes 和人类可读的 size。格式错误的账本行会被跳过并计数，而不会导致整个统计调用失败。如果下载成功，但账本追加失败，下载响应仍会成功，并在 JSON 输出中包含 history_error。

CLI 参考

CLI 负责进程设置和诊断；媒体操作通过 MCP 工具提供。

命令	用途
rytdl 或 rytdl serve	通过 stdio 提供 MCP 服务。这是客户端使用的默认运行方式。
rytdl setup	在需要时获取工具依赖项，并注册本地 MCP 客户端。
rytdl doctor	输出版本、平台、工具解析和配置存在情况的诊断信息。

npm 启动器提供相同的二进制文件：

npx -y @dinglebear/rytdl doctor
npx -y @dinglebear/rytdl serve

安装

通过 npm 运行引导式安装程序：

npx -y @dinglebear/rytdl setup

或者全局安装命令：

npm i -g @dinglebear/rytdl
ytdl-rmcp setup

npm 包会在 postinstall 期间下载匹配的 GitHub Release 二进制文件；安装的命令是通过一个精简的 Node 启动器运行的 Rust 二进制文件。你也可以使用单行安装程序：

curl -fsSL https://raw.githubusercontent.com/dinglebear-ai/rytdl/main/scripts/install.sh | bash

或者从 Releases 下载适用于你平台的二进制压缩包，或自行构建（见下文）。 引导式设置会获取 yt-dlp + ffmpeg，提示你设置音频/视频目标路径，检测已安装的 Agent CLI，并将服务注册到你选择的客户端中。

快速入门

设置完成后，先验证只读流程：

npx -y @dinglebear/rytdl doctor

对于原始 MCP 客户端，使用 JSON-RPC tools/call 调用只读工具：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "youtube_search",
    "arguments": {
      "query": "lcd soundsystem live",
      "limit": 3,
      "response_format": "json"
    }
  }
}

然后在下载前测试一个已知 URL：

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "youtube_probe",
    "arguments": {
      "urls": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
    }
  }
}

只有在 YTDLP_TARGET_PATH 或 YTDLP_VIDEO_TARGET_PATH 指向你愿意让受信任的 MCP 调用方写入的目标位置后，才使用 youtube_download。

客户端配置

不带子命令运行时，npx -y @dinglebear/rytdl 会通过 stdio 提供 MCP 服务。你可以自行注册：

# Claude Code
claude mcp add -s user @dinglebear/rytdl -e YTDLP_TARGET_PATH=nashost:/media/music -e YTDLP_EXTRACTOR_ARGS=youtube:player_client=android -- npx -y @dinglebear/rytdl
# Codex
codex  mcp add --env YTDLP_TARGET_PATH=nashost:/media/music --env YTDLP_EXTRACTOR_ARGS=youtube:player_client=android @dinglebear/rytdl -- npx -y @dinglebear/rytdl
# Gemini CLI (command is positional, env last)
gemini mcp add -s user @dinglebear/rytdl npx -y @dinglebear/rytdl -e YTDLP_TARGET_PATH=nashost:/media/music -e YTDLP_EXTRACTOR_ARGS=youtube:player_client=android

如果你已经通过 npm i -g @dinglebear/rytdl、scripts/install.sh 或发布压缩包安装了独立二进制文件，也可以使用该二进制文件的路径替代 npx -y @dinglebear/rytdl。

对于原始 MCP JSON 配置，请包含必需的目标路径环境变量和 YouTube 提取器覆盖设置：

{
  "mcpServers": {
    "ytdl-rmcp": {
      "command": "npx",
      "args": ["-y", "@dinglebear/rytdl"],
      "env": {
        "YTDLP_TARGET_PATH": "nashost:/mnt/user/data/media/music/yt-dlp",
        "YTDLP_VIDEO_TARGET_PATH": "nashost:/mnt/user/data/media/movies/yt-dlp",
        "YTDLP_AUTO_UPDATE": "1",
        "YTDLP_MAX_AGE_DAYS": "1",
        "YTDLP_EXTRACTOR_ARGS": "youtube:player_client=android"
      }
    }
  }
}

仓库中的 .mcp.json 也是完整的原始 MCP 配置：它声明了插件/捆绑包清单中使用的相同 user_config 键，为本地网关导入提供默认值，并将每项设置映射到服务环境中。为确保 YouTube 搜索/探测行为可靠，它默认将 YTDLP_EXTRACTOR_ARGS 设置为 youtube:player_client=android； 官方音乐视频结果在元数据提取期间经常会拒绝 yt-dlp 的默认 YouTube 客户端。

运行方式

方式	命令或文件	说明
stdio MCP 服务	npx -y @dinglebear/rytdl 或 rytdl	本地 MCP 客户端的默认运行方式。
CLI	rytdl --help	同一二进制文件；提供设置和诊断功能。
引导式设置	npx -y @dinglebear/rytdl setup	在可用时注册 Claude Code、Codex 和 Gemini CLI 配置。
MCP App	youtube_search_ui	嵌入式搜索小组件，并提供常规备用工具输出。
捆绑包	mcpb/manifest.json	适用于支持捆绑包的桌面宿主的二进制 MCPB/DXT 包。
容器	ghcr.io/dinglebear-ai/rytdl:main	包含 ffmpeg、fpcalc、SSH、rclone 和 rsync，适用于共享部署。
TOOTIE 持久运行环境	ops/compose/tootie/	由产品维护的 Compose 声明；会话通过 mcp-stdio.sh 经 stdio 进入长期运行的容器。

分发协议

• npm 启动器 — npx -y @dinglebear/rytdl 会下载并运行匹配的 GitHub Release 二进制文件。不带子命令运行时，会通过 stdio 提供 MCP 服务； npx -y @dinglebear/rytdl setup 会运行引导式安装程序。稳定版由 GitHub Actions 通过 npm provenance 发布软件包。
• Claude Code 插件 — .claude-plugin/plugin.json 通过 userConfig 提示用户配置； .mcp.json 会启动 npx -y @dinglebear/rytdl，通过 npm 下载匹配的 GitHub Release 二进制文件。
• Gemini CLI 扩展 — gemini-extension.json；使用 gemini extensions install https://github.com/dinglebear-ai/rytdl 安装。 MCP 客户端应优先使用 npm 启动器命令 npx -y @dinglebear/rytdl。
• 容器镜像 — 每次推送到 main 时都会发布 ghcr.io/dinglebear-ai/rytdl:main， 也可以使用 docker build -t ytdl-rmcp:local . 在本地构建。镜像包含 ffmpeg、fpcalc、openssh-client、rclone 和 rsync。MCP 和挂载式媒体库示例请参阅 docs/container.md。
• MCP 软件包（.mcpb / .dxt） — mcpb/manifest.json 定义了 binary 类型的软件包，可在支持 MCPB 的桌面主机中一键安装。 每次主版本发布都会提供 ytdl-rmcp.mcpb，以及一个旧版别名 ytdl-rmcp.dxt； 两者都包含相同的 Linux 和 Windows 二进制文件。软件包会将可选配置值默认为空字符串，以便 Claude Desktop 可以先安装，再填写目标设置。 下载前，请至少在扩展设置中配置目标路径。 可使用 scripts/build-mcpb.sh 从预构建的二进制文件在本地构建（需要用于运行 @anthropic-ai/mcpb CLI 的 Node）。

配置

下载只需要一个必填值：YTDLP_TARGET_PATH。 只有当视频文件需要保存到与音频不同的位置时，才需要设置 YTDLP_VIDEO_TARGET_PATH。 youtube_search、youtube_probe 和 youtube_identify 不需要目标位置。安装清单会将 YTDLP_EXTRACTOR_ARGS 默认为 youtube:player_client=android，因为常见的 YouTube 元数据屏蔽会导致官方音乐视频搜索结果显示为不可用，而该客户端可以避开这些屏蔽。

目标路径格式：

• /path/to/library — 本地目录。由二进制文件自身的文件系统复制功能复制（不需要外部工具）；如果目标目录嵌套在暂存源目录中，则会被拒绝。需要设置 YTDLP_ALLOW_LOCAL_TARGETS=true，因为本地路径允许 MCP 调用方自行选择写入位置。
• host:/path/to/library — SSH 目标。使用现有的 rsync/scp 流程，并遵循 YTDLP_SSH_OPTS。
• remote:path/to/library — 使用相对远程路径的 rclone 目标。使用 rclone copy；服务器进程必须能够在 PATH 中找到已配置的 rclone。
• rclone:remote:/path/to/library — 用于绝对远程路径的显式 rclone 目标；按设计，未添加 rclone: 前缀时，host:/path 仍表示 SSH。 | 变量 | 必需？ | 默认值 | 用途 | 含义 | | --- | --- | --- | --- | --- | | YTDLP_TARGET_PATH | 下载时必需 | — | download | 音频的目标位置。本地路径使用 /path，SSH 使用 host:/path，rclone 使用 remote:path 或 rclone:remote:/path。 | | YTDLP_VIDEO_TARGET_PATH | 可选 | 回退到 YTDLP_TARGET_PATH | download | 当视频文件需要与音频存放在不同位置时，指定视频的目标位置。目标格式相同。 | | YTDLP_REMOTE | 已弃用 | — | download | 旧版 SSH 远程别名或 user@host。迁移期间，会与 YTDLP_REMOTE_PATH / YTDLP_VIDEO_REMOTE_PATH 组合为显式 SSH 目标。建议使用 YTDLP_TARGET_PATH。 | | YTDLP_REMOTE_PATH | 已弃用 | — | download | 音频的旧版 SSH 绝对路径。需要设置 YTDLP_REMOTE；不接受相对路径。建议使用 YTDLP_TARGET_PATH。 | | YTDLP_VIDEO_REMOTE_PATH | 已弃用 | — | download | 视频的旧版 SSH 绝对路径。需要设置 YTDLP_REMOTE；未设置时回退到音频目标。建议使用 YTDLP_VIDEO_TARGET_PATH。 | | YTDLP_ALLOW_LOCAL_TARGETS | 可选 | 0 | download | 允许使用本地文件系统目标，例如 /path。除非你信任 MCP 调用方选择本地写入位置，否则请保持禁用。 | | YTDLP_AUDIO_FORMAT | 可选 | mp3 | download | 默认音频编解码格式：mp3、m4a、opus、flac、wav 或 best。 | | YTDLP_STAGING_DIR | 可选 | 系统临时目录 | download | 传输前用于暂存媒体文件的本地目录。传输失败时，会保留此暂存副本以供重试。 | | YTDLP_SSH_OPTS | 可选 | — | download | 额外的 SSH 选项，按 shell 单词语法解析，并追加在强制的非交互式默认选项之后。示例：-i "~/.ssh/ytdl key" -o ProxyJump=media-bastion。格式错误的引号会被拒绝，并会移除 ProxyCommand 等可能导致命令执行风险的选项。 | | YTDLP_ARCHIVE_DIR | 可选 | 每用户状态目录 | download | 存储 use_archive 下载归档的目录。此目录中会按模式分别创建归档文件。 | | YTDLP_HISTORY_PATH | 可选 | 每用户状态目录中的 downloads.jsonl | download、stats | youtube_stats 使用的 JSONL 下载记录。 | | YTDLP_PLEX_URL | 同步到 Plex 时必需 | — | download | Plex 服务 URL，例如 http://plex.local:32400，用于将音频下载添加到 Plex 播放列表。必须与 YTDLP_PLEX_TOKEN 配套设置。 | | YTDLP_PLEX_TOKEN | 同步到 Plex 时必需 | — | download | 用于播放列表/搜索 API 调用的 Plex 身份验证令牌。必须与 YTDLP_PLEX_URL 配套设置。 | | YTDLP_PLEX_PLAYLIST | 可选 | 设置了 Plex URL/令牌时为 yt-dlp Downloads | download | 默认 Plex 播放列表标题或 ID；可在每次调用时通过 plex_playlist 覆盖。 | | YTDLP_CLEAN_METADATA | 可选 | 1 | download | 在嵌入元数据前移除 YouTube 标题中的常见杂项。设为 0 可原样保留来源标题。 | | YTDLP_ACOUSTID_CLIENT_KEY | 识别/自动重新标记时必需 | — | identify、download | AcoustID 应用 API 密钥。youtube_identify 必须设置此项；设置后，youtube_download 还会在传输前将高置信度的 MusicBrainz 标签写入已下载的音频。 | | FPCALC_PATH | 可选 | PATH 中的 fpcalc | identify、download 重新标记 | Chromaprint fpcalc 可执行文件的可选显式路径。 | | YTDLP_MUSICBRAINZ_CONTACT | 可选 | GitHub 仓库 URL | identify、download 重新标记 | MusicBrainz 查询 User-Agent 字符串中包含的联系 URL/电子邮件。 | | YTDLP_AUTO_UPDATE | 可选 | 1 | 工具引导 | yt-dlp 过期时重新下载。仅当通过 YTDLP_PATH/哈希固定值在外部管理该可执行文件时才禁用。 | | YTDLP_MAX_AGE_DAYS | 可选 | 14 | 工具引导 | yt-dlp 自动更新的过期天数阈值。 | | YTDLP_UPDATE_PRE | 可选 | 0 | 工具引导 | 跟踪 yt-dlp 的夜间预发布频道，而不是稳定版。 | | YTDLP_EXTRACTOR_ARGS | 确保 YouTube 搜索/探测可靠时必需 | 安装清单中为 youtube:player_client=android；裸进程环境中未设置 | search、probe、download | 传递给 yt-dlp --extractor-args。Android YouTube 客户端可修复官方音乐视频常见的 This video is not available 元数据错误。 | | YTDLP_TIMEOUT_SECS | 可选 | 1800 | search、probe、download | 每条 yt-dlp 搜索/探测/下载命令的超时时间。 | | YTDLP_TRANSFER_TIMEOUT_SECS | 可选 | 600 | download | 每个传输阶段的超时时间。 | | YTDLP_PATH | 可选 | — | 工具引导 | 使用指定的 yt-dlp 可执行文件，而不是自动解析/自动下载。 | | FFMPEG_PATH | 可选 | — | 工具引导、download | 使用指定的 ffmpeg 可执行文件，而不是自动解析/自动下载。探测/搜索不需要 ffmpeg。 | | YTDLP_SHA256 | 可选 | — | 工具引导 | 已解析的 yt-dlp 可执行文件必须满足的可选 SHA-256 摘要。 | | FFMPEG_SHA256 | 可选 | — | 工具引导 | 已解析的 ffmpeg 可执行文件必须满足的可选 SHA-256 摘要。 | | YTDLP_LOG | 可选 | info | 服务进程 | 仅写入 stderr 的 tracing 过滤器。切勿将日志发送到 stdout，因为 stdout 是 MCP JSON-RPC 通道。 |

维护者： 此表由人工维护。scripts/check-packaging.sh 会交叉检查机器可读的配置项（Claude 插件、 .mcp.json user_config、gemini-extension.json 和 mcpb/manifest.json），并验证此 README 提及了所有映射的环境变量名称。 它不会比较 README 中的描述或默认值。添加、重命名或删除 YTDLP_*、FFMPEG_*、FPCALC_PATH 或 YTDLP_LOG 环境变量时，请手动更新此 表。

身份验证

此服务仅使用 stdio——不会打开网络监听器、绑定端口，也没有 HTTP 身份验证层。访问权限取决于本地 MCP 客户端授予其启动进程的权限。外部 凭据存储在由操作人员控制的环境变量、本地配置、SSH 代理、rclone 配置或 Plex/AcoustID 变量中。

MCP 调用方不会在工具参数中提供 Plex 令牌、SSH 密钥、rclone 凭据、哈希固定值 或下载器二进制文件路径。工具参数包含媒体 URL、 搜索/探测输入、输出模式选项和目标选择器，这些内容会根据进程配置进行验证。

安全与信任模型

引导信任模型

默认情况下，首次运行时按以下顺序解析工具：显式环境变量覆盖、 PATH、缓存，然后通过 HTTPS 从上游发布源下载。设置 YTDLP_SHA256 和/或 FFMPEG_SHA256，即可在解析或下载后要求可执行文件的摘要完全匹配。这些固定值会验证磁盘上的文件，但不会获取上游签名，也不会自动发现可信摘要；需要完全固定供应链的操作人员应通过 YTDLP_PATH / FFMPEG_PATH 提供已知可信的二进制文件及匹配的 SHA-256 固定值，或禁用 yt-dlp 自动更新。

若要更严格地控制引导过程，请将 YTDLP_PATH / FFMPEG_PATH 与匹配的 YTDLP_SHA256 / FFMPEG_SHA256 固定值结合使用。哈希固定值会验证解析出的 可执行文件字节；它们不等同于上游签名验证。

安全态势

此服务旨在配合可信调用方和操作人员提供的配置运行——它不是经过加固的多租户隔离边界。

• 工具调用中的 URL 会传给 yt-dlp。 MCP 调用方传入的任何 urls 都会 交给 yt-dlp，这是一种功能强大的提取工具。只允许你信任的调用方使用它。工具调用中的 URL 在传给 yt-dlp 前会验证为 http/https，并且每个位置参数都会放在 -- 选项结束分隔符之后传递，因此以 - 开头的值不会被解析为标志；但无论如何，上述信任假设依然成立。
• SSH 仅使用密钥，且为非交互式。 SSH 目标会强制设置 BatchMode=yes 和 StrictHostKeyChecking=accept-new，因此没有 TTY 的服务会快速失败，而不会发出提示；不支持密码身份验证。身份验证使用你的 SSH 密钥/代理，以及你通过 YTDLP_SSH_OPTS 添加的任何选项。
• 目标路径会经过验证。 本地和 SSH 路径必须是绝对路径，且不得包含路径遍历内容或控制字符。SSH 远程目标还会拒绝类似选项的值以及包含空白字符/控制字符的值，确保这些内容不会传给 ssh/rsync/scp；远程路径会针对远程 shell 进行单引号转义。Rclone 目标必须为 remote:path 或显式的 rclone:remote:/path，且不得包含控制字符。

要求

• rsync 推荐用于 SSH 传输；若未安装，则回退到 scp。 本地传输无需外部工具——二进制文件会自行复制整个目录树。
• 使用 host:/path 目标时，需要 ssh 以及免密码的密钥身份验证。
• 使用 remote:path 或 rclone:remote:/path 目标时，需要 rclone 以及已配置的 rclone 远程端。
• yt-dlp 和 ffmpeg 会自动获取（可通过 YTDLP_PATH / FFMPEG_PATH 覆盖，或直接将它们放入 PATH）。
• youtube_identify 还需要 fpcalc；容器镜像通过 libchromaprint-tools 包含该工具。

开发

从源代码构建并测试：

cargo build --release                                          # Linux/macOS
cargo test && cargo clippy --all-targets -- -D warnings        # checks

# Cross-compile to Windows from Linux (needs nasm + the LLVM toolchain):
sudo apt-get install -y nasm llvm clang lld
cargo install cargo-xwin
cargo xwin build --release --target x86_64-pc-windows-msvc

在 devhost/本地 shell 中，~/.local/bin/cargo 是一个可能导致 cargo xwin 出错的包装程序；在本地进行 Windows 演练时，请使用真正的 rustup cargo：

~/.cargo/bin/cargo xwin build --release --target x86_64-pc-windows-msvc

CI（.github/workflows/）会在每次推送或 PR 时运行 fmt、clippy、测试和 Windows 交叉构建，并在 v* 标签上将两个二进制文件发布到 GitHub Release。

此单 crate 工作区使用 Rust edition 2024，MSRV 为 1.97.1。

验证

发布 README、软件包或运行时变更之前，请执行以下检查：

python3 /home/jmagar/workspace/soma/scripts/check-readme-guide.py README.md packages/ytdl-rmcp/README.md
npm --prefix packages/ytdl-rmcp run check
cargo fmt --check
cargo check
cargo test
scripts/check-packaging.sh
git diff --check

进行实时 MCP 冒烟测试时，请使用临时配置进行注册，并先调用 youtube_search 或 youtube_probe，再运行 youtube_download。

架构

直接调用程序时，会通过 stdio 提供 MCP 服务；setup 会运行安装程序。调用 youtube_download 时：

1. 解析 yt-dlp 和 ffmpeg（环境变量覆盖 → PATH → 缓存 → 下载），并在配置了 SHA-256 固定值时进行验证。
2. 清理混合/电台 URL，然后按模式运行 yt-dlp，将文件输出到暂存目录树（staging/audio、staging/video），并设置元数据/缩略图/存档标志、源元数据 sidecar，以及 Artist/Title [id] 输出模板。
3. （可选） 设置 YTDLP_ACOUSTID_CLIENT_KEY 后，为下载的音频生成指纹，并在原文件上写入高置信度的 MusicBrainz/AcoustID 标签——在传输前完成，因此目标副本会带有规范标签。
4. 将每种类型的子目录传输到其目标位置：本地进程内复制、SSH rsync/scp，或 rclone copy。
5. （可选） 配置了 Plex 凭据且传输成功后，将下载的音轨添加到目标 Plex 播放列表。
6. 将已完成的调用追加到 JSONL 下载记录中。
7. 返回 Markdown 或 JSON 摘要，列出文件、大小和实际目标位置。

架构、约定和注意事项请参阅 CLAUDE.md。

部署

• 本地客户端应通过 stdio 使用 npx -y @dinglebear/rytdl 或已安装的 rytdl 二进制文件。
• 如果希望无需在主机级别安装 ffmpeg、fpcalc、SSH、rclone 和 rsync，共享运行时作业可以使用容器镜像。
• 在向调用方开放 MCP 服务之前，主机部署应在进程环境变量或主机配置中设置目标位置、Plex、AcoustID、SSH 和 rclone 凭据。
• 除非允许受信任的调用方写入通过工具参数选择的本地文件系统路径，否则请将 YTDLP_ALLOW_LOCAL_TARGETS=0 保持不变。

故障排除

• YouTube 元数据似乎不可用：设置 YTDLP_EXTRACTOR_ARGS=youtube:player_client=android，或使用仓库中自带的客户端/插件配置，它们已默认设置此项。
• 下载成功但传输失败：检查 staging_kept_at 或 youtube_transfer_queue 列表，修复 SSH、rclone 或本地目标权限问题后重试。
• Plex 播放列表未更新：确认 YTDLP_PLEX_URL、YTDLP_PLEX_TOKEN 已设置，并确认 Plex 可以访问已传输的文件。
• 工具引导流程对你的环境限制不足：为 YTDLP_PATH 和 FFMPEG_PATH 指定路径，并设置匹配的 SHA-256 变量，或禁用 yt-dlp 自动更新。

相关服务

• soma - 为由提供商支持的 MCP 服务提供 RMCP 运行时。
• unifi-rmcp - UniFi 控制器 REST API 桥接服务。
• tailscale-rmcp - 面向设备、用户和 tailnet 操作的 Tailscale API 桥接服务。
• unraid - 用于 NAS 和服务器管理的 Unraid GraphQL 桥接服务。
• apprise-rmcp - 支持多种投递后端的 Apprise 通知分发桥接服务。
• gotify-rmcp - 用于发送通知、管理消息、应用和客户端的 Gotify 推送通知桥接服务。
• arcane-rmcp - 用于管理容器及相关资源的 Arcane Docker 桥接服务。
• yarr - 面向 Sonarr、Radarr、Prowlarr、Plex 及相关服务的媒体栈桥接服务。
• synapse-rmcp - 用于 scout 和 flux 操作的本地 Synapse 工作流服务。
• cortex - Syslog 和 homelab 日志聚合 MCP 服务。
• axon - RAG、爬取、抓取、提取和语义搜索项目。
• labby - Homelab 控制平面和 MCP 网关项目。
• lumen - 本地语义代码搜索 MCP 服务。

文档

本 README 是经过整理的运维入口。生成的或机器可读的事实来源位于包、插件和 bundle 清单中，scripts/check-packaging.sh 会对它们进行交叉检查。

文档	用途
CLAUDE.md	架构、约定和本地 Agent 说明。
docs/container.md	容器运行时示例和挂载库模式。
docs/musicbrainz-acoustid.md	规范元数据匹配和重新标记行为。
.mcp.json	原始 MCP 配置文件和机器可读的用户配置默认值。
.claude-plugin/plugin.json、gemini-extension.json、mcpb/manifest.json	特定客户端的打包元数据。

许可证

本项目中由 Dinglebear 原创的部分依据 AGPL-3.0-only 许可。对于需要 AGPL 以外许可条款的组织，也提供单独的商业许可。第三方材料仍遵循其原始许可证。请参阅 LICENSING.md。

Rust MCP 命名模式

本仓库遵循 Rust MCP 服务命名约定：

• 仓库：dinglebear-ai/rytdl
• Cargo crate：ytdl-rmcp
• CLI 别名：rytdl
• npm 包：@dinglebear/rytdl