YTDL RMCP

ytdl-rmcp

MCP と CLI を通じて、yt-dlp による検索、ダウンロード、メタデータ取得、転送、Plex ワークフローを実行します。

rmcp クレートを使用して Rust で実装されています。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 クレート	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 リスナーなし、サービス用ポートなし

クレートと npm パッケージには *-rmcp ファミリーの命名パターンを使用し、 リポジトリとランタイムバイナリは rytdl としています。これにより、ローカルシェルから 短い Rust ネイティブのコマンドを使えます。

機能と境界

• メディアをダウンロードせずに、yt-dlp を通じて YouTube を検索します。
• 音声、動画、または両方をステージングツリーにダウンロードし、音声メタデータにタグを付け、 ローカル、SSH、または rclone の保存先へ転送します。
• オプションで AcoustID/MusicBrainz を通じて音声のフィンガープリントを作成し、完了した 音声ダウンロードを Plex プレイリストに同期します。
• 成功した転送履歴から Plex プレイリストを作成し、サーバーで作成された保持中のステージング転送マニフェストを処理します。
• 埋め込みウィジェットを表示できるホスト向けに、MCP App 検索 UI を公開します。
• 再実行しても安全なダウンロードと統計のために、JSONL 台帳を保持します。

このリポジトリの担当	上流の担当	明示的な対象外
MCP ツール、CLI セットアップ、メディアのステージング、タグ付け、転送ポリシー、キューマニフェスト、設定検証、レスポンス整形、プラグイン／パッケージのメタデータ。	yt-dlp の抽出動作、ソースサイトの可用性、ffmpeg によるメディア変換、Plex ライブラリのインデックス作成、SSH/rclone の認証。	マルチテナント分離、信頼できない呼び出し元による任意のローカル書き込み、認証情報の仲介、サイト固有のスクレイピング保証、メディアサーバーの代替。

---

機能

• 音声、動画、または両方 — デフォルトでは音声を優先し、音声と動画それぞれに別のターゲットを指定できます。
• 適切なタグ付け — タイトル／アーティスト／アルバム／日付とカバーアートを埋め込み、出力を Artist/Title [id].ext の形式で整理するため、メディアサーバー（Plex など）で正しくインデックス化できます。非貪欲な Artist - Title の解析により、自由形式の動画タイトルからアーティストを復元します。ソースの .info.json、サムネイル、説明のサイドカーファイルは、将来のタグ付けやインデックス作成に備えてメディアの隣に保持されます。(Official Video)、[Official Audio]、末尾のチャンネルハンドルなど、YouTube のタイトルによく含まれる不要な文字列は、デフォルトで埋め込みタイトルのメタデータから除去されます。
• 自己完結型のパス — バイナリを直接実行すると、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 は、シード動画の URL に自動的に整理されます。
• 統計に対応した台帳 — ダウンロード呼び出しが完了するたびに、タイムスタンプ、保存先、ファイル、バイト数、アップローダー、転送ステータスを含む JSONL エントリを追加します。
• Plex プレイリストの同期 — Plex の認証情報が設定されている場合、ダウンロードした音声はデフォルトで yt-dlp Downloads に追加されます。

MCP ツールリファレンス

ツール	用途
youtube_search	yt-dlp で YouTube を検索し、ダウンロードせずに結果の URL を返します。
youtube_search_ui	MCP App 対応ホストで、インタラクティブな YouTube 検索 UI を開きます。
youtube_download	1 つ以上の URL をダウンロード（音声／動画／両方）し、ターゲットパスに転送します。
youtube_probe	読み取り専用です。ダウンロードせずにタイトル／再生時間／アップローダー／形式数を解決します。
youtube_identify	fpcalc でローカル音声のフィンガープリントを作成し、AcoustID／MusicBrainz の候補を返し、標準タグをプレビューして、信頼度が高い場合はタグを書き込みます。
youtube_stats	ダウンロード台帳の概要を表示します。合計、ファイル種別、アップローダー、最近のエントリを確認できます。
youtube_plex_playlist	転送に成功した音声の履歴から、Plex の音声プレイリストを作成またはプレビューします。
youtube_transfer_queue	保持されたステージング用の転送失敗マニフェストを一覧表示し、処理します。

youtube_download のパラメーター

パラメーター	デフォルト	説明
urls	—（必須）	1 つの URL 文字列、または URL の配列です。
mode	audio	audio、video、または both です。
audio_format	環境変数 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	環境変数 YTDLP_TARGET_PATH	音声の保存先です。ローカルの場合は /path、SSH の場合は host:/path、rclone の場合は remote:path または rclone:remote:/path を指定します。
video_target_path	環境変数 YTDLP_VIDEO_TARGET_PATH → target_path	動画を音声とは別の場所に保存する場合の保存先です。同じ形式を使用します。
keep_local	false	転送後もローカルのステージングコピーを保持します。
use_archive	false	ダウンロード済みの ID を記録し、スキップします（モードごと）。
plex_playlist	環境変数 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 レスポンスには、matched、added、already_present、missing の件数を含む plex_playlist の概要が含まれます。

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 を指定して、1 つのマニフェストを再試行します。
retry_all	保留中のすべてのマニフェストを再試行します。
prune	ステージングディレクトリが存在しないマニフェストを削除します。

キューは任意のファイルシステムパスを受け付けません。再試行では、失敗時に記録された元の転送先パスを使用し、転送前にローカルの転送先ポリシーを再確認します。ステージングディレクトリ、マニフェスト ID、ファイルリスト、元の転送先が引き続き一致している場合に、転送が失敗するとローカルサーバーがマニフェストを作成します。

youtube_identify のパラメーター

パラメーター	デフォルト	意味
paths	—（必須）	ローカルのオーディオファイルパス文字列 1 つ、またはパスの配列です。
write_tags	false	信頼度の高い MusicBrainz タグプレビューをオーディオファイルに書き戻します。
response_format	markdown	markdown または json です。

youtube_identify は Chromaprint の fpcalc を実行し、フィンガープリントを AcoustID に送信して、MusicBrainz の録音候補を返します。最適な候補の信頼度が高い場合は、MusicBrainz の録音／リリースデータも取得し、正規化されたアーティスト、タイトル、リリース、リリース日、リリース種別、トラック番号、MusicBrainz ID を示す retag_preview を含めます。デフォルトではプレビューのみです。write_tags=true にすると、Lofty を使用してプレビューをファイルに書き込みます。一般的なタイトル／アーティスト／アルバム／日付／トラックの各フィールドに加え、MusicBrainz の録音、リリース、リリースグループ、リリース種別のタグも書き込みます。YTDLP_ACOUSTID_CLIENT_KEY が必要です。fpcalc が PATH にない場合は、FPCALC_PATH を設定してください。

youtube_search のパラメーター

パラメーター	デフォルト	意味
query	-（必須）	YouTube の検索テキストです。サーバーはこれを ytsearchN:<query> として yt-dlp に渡します。
limit	10	結果数です。1..=25 の範囲に制限されます。
response_format	markdown	markdown または json です。

youtube_search_ui は同じ入力を受け付け、同じ検索ペイロードに加えて、埋め込み UI を表示できるホスト向けの MCP App メタデータを返します。アプリを表示できないホストにも、通常の検索結果テキストと構造化データが返されます。

MCP App パターン

youtube_search_ui は、このリポジトリにおけるウィジェット対応のエントリーポイントです。

• ツール記述子は _meta.ui.resourceUri を通知します。
• サーバーは resources/list と resources/read を通じて ui://ytdl-rmcp/youtube-search.html を公開します。
• リソースは text/html;profile=mcp-app と明示的な CSP メタデータブロックを使用します。
• .mcpb／.dxt パッケージングではローカルサーバーがインストールされます。UI リソースは引き続き MCP tools/resources プロトコルを通じて通知され、ホストによって表示されます。

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 バイナリです。1 行のインストーラーも利用できます：

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

または、お使いのプラットフォーム用のバイナリ tarball を Releases からダウンロードするか、ビルドしてください（下記を参照）。 ガイド付きセットアップでは、yt-dlp と ffmpeg を取得し、音声／動画の保存先 パスを尋ね、利用可能なエージェント 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、またはリリース tarball でスタンドアロンバイナリをすでにインストールしている場合は、 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 を優先してください。
• コンテナーイメージ — ghcr.io/dinglebear-ai/rytdl:main は main へのプッシュごとに公開されます。または、docker build -t ytdl-rmcp:local . でローカルにビルドできます。ffmpeg、fpcalc、openssh-client、rclone、rsync が含まれています。MCP およびマウントしたライブラリの例については、docs/container.md を参照してください。
• MCP バンドル（.mcpb / .dxt） — mcpb/manifest.json は、MCPB 対応デスクトップホストでワンクリックインストールできる binary タイプのバンドルを定義します。すべての main リリースで 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 — ローカルディレクトリです。バイナリ独自のファイルシステムコピーでコピーされます（外部ツール不要）。ステージング元の内部にある保存先は拒否されます。ローカルパスを指定すると、MCP の呼び出し元が書き込み先を選択できるため、YTDLP_ALLOW_LOCAL_TARGETS=true が必要です。
• 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 オプションです。例：-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 retagging | Chromaprint の fpcalc 実行ファイルの明示的なパスです。 | | YTDLP_MUSICBRAINZ_CONTACT | 任意 | GitHub リポジトリの URL | identify, download retagging | MusicBrainz の検索用 User-Agent 文字列に含める連絡先 URL／メールアドレスです。 | | YTDLP_AUTO_UPDATE | 任意 | 1 | tool bootstrap | 古くなった場合に yt-dlp を再ダウンロードします。YTDLP_PATH／ハッシュのピン留めによって実行ファイルを外部で管理している場合に限り、無効にしてください。 | | YTDLP_MAX_AGE_DAYS | 任意 | 14 | tool bootstrap | yt-dlp の自動更新を行うまでの日数です。 | | YTDLP_UPDATE_PRE | 任意 | 0 | tool bootstrap | 安定版ではなく、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 | 任意 | — | tool bootstrap | 自動解決／自動ダウンロードの代わりに、指定した yt-dlp 実行ファイルを使用します。 | | FFMPEG_PATH | 任意 | — | tool bootstrap, download | 自動解決／自動ダウンロードの代わりに、指定した ffmpeg 実行ファイルを使用します。プローブ／検索では ffmpeg は不要です。 | | YTDLP_SHA256 | 任意 | — | tool bootstrap | 解決された yt-dlp 実行ファイルに要求する SHA-256 ダイジェストです。 | | FFMPEG_SHA256 | 任意 | — | tool bootstrap | 解決された ffmpeg 実行ファイルに要求する SHA-256 ダイジェストです。 | | YTDLP_LOG | 任意 | info | server process | stderr のみに書き込まれる tracing フィルターです。stdout は MCP JSON-RPC チャネルであるため、ログを stdout に送信しないでください。 |

メンテナー向け： この表は手作業で管理されています。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 に渡される前に、オプションのような値や空白文字／制御文字を含む値が拒否されます。 リモートパスはリモートシェル向けにシングルクォートでエスケープされます。rclone の接続先は remote:path または明示的な rclone:remote:/path でなければならず、制御文字は拒否されます。

要件

• SSH 転送には rsync の使用を推奨します。利用できない場合は 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／ローカルのシェルでは、~/.local/bin/cargo は cargo xwin が正常に動作しなくなる可能性があるラッパーです。ローカルで Windows 向けの動作確認をする場合は、本物の rustup cargo を使用してください。

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

CI（.github/workflows/）では、すべての push／PR で fmt、clippy、テスト、および Windows クロスビルドが実行され、v* タグでは両方のバイナリが GitHub Release に公開されます。

この単一クレートのワークスペースでは、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_download を実行する前に youtube_search または youtube_probe を呼び出してください。

アーキテクチャ

引数なしで起動すると stdio 経由で MCP を提供し、setup を実行するとインストーラーが起動します。youtube_download の呼び出しでは、次の処理が行われます。

1. yt-dlp と ffmpeg を解決し（環境変数による上書き → PATH → キャッシュ → ダウンロード）、設定されている場合は SHA-256 のピンを検証します。
2. ミックス／ラジオの URL をクリーンアップし、モードごとに yt-dlp を実行して、メタデータ／サムネイル／アーカイブのフラグ、ソースメタデータのサイドカー、および Artist/Title [id] の出力テンプレートを使い、ステージングツリー（staging/audio、staging/video）に保存します。
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 とホームラボのログを集約する MCP サーバーです。
• axon - RAG、クロール、スクレイピング、抽出、セマンティック検索を行うプロジェクトです。
• labby - ホームラボのコントロールプレーンと MCP ゲートウェイのプロジェクトです。
• lumen - ローカルのセマンティックコード検索 MCP サーバーです。

ドキュメント

この README は、運用者向けの厳選されたエントリーポイントです。生成された、または機械可読な信頼できる情報源はパッケージ、プラグイン、バンドルのマニフェストにあり、scripts/check-packaging.sh が相互に照合します。

Doc	目的
CLAUDE.md	アーキテクチャ、規約、ローカルエージェントに関するメモです。
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 クレート：ytdl-rmcp
• CLI エイリアス：rytdl
• npm パッケージ：@dinglebear/rytdl