VideoNote-Mcp は「動画リンク → 多形式ノート」のパイプライン全体を MCP Server + Claude Code Skill としてパッケージ化したものです。エージェントにリンクを渡すだけで、ダウンロード → 音声文字起こし → 映像理解 → 弾幕/コメント → AI 要約を自動で実行し、スクリーンショット付きで丸ごと移設可能なポータブルノートを返します。

リポジトリ：HuangYincan/VideoNote-MCP。

本プロジェクトは**エンドツーエンドでの利用（1つのリンク → 1つのノート）**も、分離しての利用も可能です。パイプラインの各段階（ダウンロード / 文字起こし / フレーム抽出 / コメント / 要約 / エクスポート / 拡張 / クリーンアップ）はすべて独立した MCP ツールであり、特定のステップだけを使いたい場合や、動画の内容を把握したいだけの場合にも対応します。バックエンドサービスの起動は不要です。

⚡ クイックスタート

# 1) 一条命令装好 Skill + MCP（插件 marketplace，uvx 自动更新）
claude plugin marketplace add HuangYincan/VideoNote-MCP
claude plugin install videonote@videonote

# 2) 安装时 Claude Code 会逐项提示默认值（风格/转写引擎/视频理解/评论等）；
#    装完在会话里跑配置向导收尾：
/videonote-setup

# 3) （可选）LLM-Key/B 站扫码/CLI向导
# ! videonote setup

# 4) 重启会话，对 agent 说「帮我给这个视频做笔记」+ 链接

[!TIP] 4 種類のインストール方法、設定の詳細、更新とセキュリティについては docs/04-使用手册.md を参照してください。

Related MCP server: tldw-mcp

📚 ドキュメント

インストール / 設定 / 使用方法 / 環境変数 / 更新 / セキュリティなどの完全な説明は docs/ にアーカイブされています（README には概要のみ記載）：

• 📇 ドキュメント索引

• 🏗️ アーキテクチャ設計

• 📖 使用マニュアル —— インストール（4 種類）· 設定（setup ウィザード + CLI）· 環境変数 · 更新 · セキュリティ

• 📜 更新ログ

🎬 実例

2 つのエンドツーエンドの実例：1 つは AGENT 直接生成で LaTeX mathnote PDF を出力、もう 1 つは 全自動 LLM 生成でポータブル Markdown を出力します。

事例 1 · agent_direct + LaTeX mathnote（DeepSeek-V4 動画）

出典：【闪客】深入解读 DeepSeek V1~V4！男女老少都听得懂～](https://www.bilibili.com/video/BV1rpovBCEGH/?vd_source=2a93b97e35c51587de18c73fcf753191)

1 本の動画 + 4 種類の外部資料（論文 / テクニカルレポート / 公式アカウント発表 / オープンソースコレクション）→ AGENT 直接生成による精錬ノートを作成し、LaTeX mathnote PDF（中国語楷書テンプレート）を出力：

特長：agent_direct 全フロー（LLM key 不要、Agent が文字起こし + フレーム画像 + コメントを読んでノートを自動作成）· 複数ソースのクロス統合（動画 × 論文 × テクニカルレポート × オープンソースリスト）· 精錬版と原稿の両方を保存（note.md / note_original.md の 2 部）· LaTeX mathnote PDF（フォント欠落 / 改行オーバーフロー / 引用重複を自動修復）。完全なプロセス記録は examples/agent-direct-deepseek-v4-mathnote/README.md を参照してください。

事例 2 · 全自動 LLM 生成 + ポータブル Markdown（複数動画の並列処理）

極めてシンプルな Prompt（B 站リンク 3 つ + 出力ディレクトリ、パラメータの説明は一切なし）→ 全自動で 環境チェック → リンク識別 → プロバイダー/モデル検出 → パラメータ確認 → 複数動画の並列処理 → 生成後に字幕に基づいて精錬し、3 部の精錬ポータブルノート（note.md + Assets/ スクリーンショット + 「視聴者の意見」セクション、比較用に note_original.md も保存）を作成。

• 雅思：誤解の解消 + リスニング/リーディング/ライティング/スピーキング 4 科目の分解 + 高頻出考点語 179 語 + 論理フレームワーク 15 文

• 法医：43 年のベテラン法医が「フィルム解説」で映像と現実を比較、精錬して 12 節に拡充

• Transformer：自己注意機構の詳細解説、講義タイムラインに沿って 18 枚のスクリーンショットを配置

完全なプロセス記録は examples/note-generation-example/README.md を参照してください。

🗺️ パイプライン概要

flowchart LR
    A["视频链接"] --> B["下载音视频<br/>+ 平台字幕"]
    B --> C["语音转写<br/>或直接用平台字幕"]
    B -. 可选 .-> D["逐帧画面理解<br/>关键帧 → 网格图"]
    B -. 可选 .-> E["弹幕 + 评论区"]
    C --> F["素材包<br/>转写 · 帧 · 评论"]
    D -.-> F
    E -.-> F
    F --> G["AI 总结 → Markdown 底稿<br/>正文 + 截图 + 「观众观点」"]
    G --> O1["便携笔记<br/>note.md + Assets/"]
    G --> O2["字幕导出<br/>SRT · VTT · JSON"]
    G -. Agent 生成 .-> O3["创意格式<br/>思维导图 · 闪卡 · LaTeX · typst"]
    G -. 可选 .-> O4["基于完整字幕精修<br/>保留原版对比"]

0 🔄 エンドツーエンド全フロー

エンドツーエンドモードではリンクを 1 つ渡すだけです。generate_note がパイプライン全体を非同期で実行し task_id を返します。軽量な get_task_status でスナップショットをポーリングして SUCCESS/FAILED/CANCELLED まで確認します（単一プロセスで最大 3 つの進行中タスク、同じメッセージ内で並列送信しないでください）。cancel_note は協調的キャンセルです。「AGENT 直接生成」は prepare_note_material を使用します —— 素材パックの準備のみ行い、設定済み LLM を呼び出さず、agent 自身が文字起こしを読み、画像を見て、ノートを書きます。

1 📥 ダウンロードとプラットフォーム解析

inspect_video はプラットフォームを識別（bilibili / youtube / douyin / tiktok / kuaishou / local；組み込み 6 プラットフォーム以外は platform:"generic" を返し、自動で yt-dlp 汎用抽出により 1800+ サイトに対応）+ リンクの有効性をチェック（無効な場合は理由を直接返す）+ B 站の分 P / YouTube プレイリストを各エピソードが独立して送信できる url に分割（ダウンロードはしない）。プラットフォームの Cookie は ! videonote login bilibili / ! videonote setup を使用し、MCP 経由で渡さないでください。プラットフォームの字幕（B 站 AI 字幕を含む）は generate_note 内部で優先的に使用され、独立したツールはありません。

2 🎙 音声文字起こし（ASR）

音声文字起こし（ASR）は generate_note 内部で実行されます：プラットフォームの字幕（B 站 AI 字幕を含む）を優先し、字幕がない場合は文字起こしを実行します。エンジンは選択可能：fast-whisper（ローカル）/ groq / bcut / kuaishou（クラウド）/ mlx-whisper（macOS Apple Silicon GPU）/ funasr（中国語に最適、VAD + 自動句読点）。エンジンとモデルの管理は CLI 経由：! videonote transcriber set/download；状態確認は get_config()。

3 🖼️ 映像理解（フレーム抽出）

generate_note は映像理解パラメータを直接サポート：video_understanding=True + video_interval（デフォルト 6s）+ grid_size（デフォルト [3,3]）。グリッド画像をマルチモーダル LLM に送信して映像を「見」ます。

4 💬 弾幕とコメント

generate_note に include_comments=True + comments_limit（デフォルト 20）を追加すると、弾幕のスクロール表示とコメント欄の高頻度意見をノートに整理し、「視聴者の意見」セクションを追加します（B 站 SESSDATA が必要；取得失敗してもタスクは中断されません）。

5 ✍️ AI 要約とノート

9 種類のスタイルに対応：minimal / detailed / academic / tutorial / xiaohongshu / life_journal / task_oriented / business / meeting_minutes；format=["screenshot"] でポータブルノート（note.md + Assets/、相対参照で丸ごと移設可能）を作成。プロバイダー/モデル/文字起こしエンジンの設定はすべて CLI 経由（! videonote providers set / ! videonote transcriber set）、読み取り専用の確認は get_config()。agent_direct は AGENT が直接生成します。

6 📤 多形式エクスポート

機械的形式は export_transcript（srt / vtt / json）を使用 —— 決定的レンダリング（タイムライン換算）、LLM を消費せず、file:// パスを返します。クリエイティブ形式（マインドマップ / フラッシュカード / LaTeX / typst / ユーザーカスタムテンプレート）は Agent が MD ベース原稿 + SKILL テンプレートに基づいて生成します（LaTeX には Math Note / English Article テンプレート内蔵：数学/理工系ノート風、英文原稿/プレゼン概要風；typst には zju-lab テンプレート内蔵：理工系ノート/実験レポート/論文風、ZJU 校章付き）。

7 🎛️ 音声拡張

merge_audio は複数の録音 / 会議の分割セグメント / 複数のローカル動画を 16kHz mono wav に結合してから文字起こしします。音声前処理（16kHz 正規化 + 超長 >1800s の自動分割、オプションでノイズ低減）はデフォルトでオフ、ハード依存関係ゼロ。diarize_media は話者分離を実行します（pyannote オプションの重い依存関係、HF_TOKEN + モデル認可が必要）。

8 🗂️ タスク管理とクリーンアップ

各タスクに 1 つのフォルダ note_results/{task_id}/：raw/（ダウンロードしたメディア）+ gen/（文字起こし/ノート/フレーム/エクスポート）+ 制御ファイル；グローバルタスク索引は SQLite video_tasks テーブル（セマンティックタイトル付き）。list_tasks は全タスクを列挙（セマンティックタイトルで識別）、cleanup_note(dry_run=True) は確認してから削除、cleanup_note / cleanup_all はタスク単位 / グローバルでクリーンアップ（デフォルトで設定とモデルを保持）、health_check は FFmpeg / データベース / whisper の準備状態をチェックします。

flowchart TB
    DATA["data/ 数据根"] --> R["note_results/ 任务目录"]
    DATA --> DB[("video_note.db<br/>SQLite 全局任务索引")]
    R --> T1["任务 A<br/>note_results/{task_id}/"]
    R --> T2["任务 B<br/>…"]
    R --> T3["任务 C<br/>…"]
    T1 --> RAW["raw/ 原始材料<br/>音视频 · 封面"]
    T1 --> GEN["gen/ 生成材料"]
    T1 --> CTRL["status.json · result.json · manifest.json"]
    GEN --> T1A["transcript.json 转写全文"]
    GEN --> T1B["note.md 成稿笔记"]
    GEN --> T1C["Assets/ 笔记内截图"]
    GEN --> T1D["frames/ 关键帧原图"]
    GEN --> T1E["srt / vtt / json 字幕导出"]
    DB -. 索引 .-> T1

🏆 ベストプラクティス

• 学習・試験対策：エンドツーエンド + 映像理解 + 字幕ベースの後続最適化で、講義を徹底的に理解。

• 会議議事録：merge_audio で分割録音を結合 → diarize_media で話者分離 → meeting_minutes スタイル。

• 講義の精読：エンドツーエンド生成後、agent が完全な字幕に基づいて精錬し、章ごとに詳細を補完。

• 動画の鑑賞：弾幕 + コメント統合を有効化、ノートに「視聴者の意見」セクションを含める。

• エンドツーエンド：1 つのリンクを generate_note に渡す（ダウンロード/文字起こし/要約/コメントの全フローを内部で実行）；素材のみ準備する場合は prepare_note_material。

• 実例：完全な事例プロセス記録は examples を参照。

🤝 コントリビューション

• 機能ブランチ → PR → dev（CI スモークテストが成功すること）；dev が安定したら PR → main（保護ブランチ、レビュー必須）。

• フロー、ブランチ命名、コミット前の自己チェックは CONTRIBUTING.md を参照。

🙏 謝辞

コミュニティとすべてのコントリビューターに感謝します。Glama による MCP server の収録、およびすべてのオープンソース依存関係と上流パイプラインプロジェクトからの示唆に感謝します。