VideoNote-Mcp empaqueta toda la canalización de «enlace de video → notas en múltiples formatos» como MCP Server + Claude Code Skill: dale un enlace al agente y automáticamente completa descarga → transcripción de voz → comprensión visual → danmaku/comentarios → resumen con IA, y devuelve una nota portátil con capturas de pantalla que se puede trasladar por completo.

Repositorio: HuangYincan/VideoNote-MCP.

Este proyecto puede usarse de extremo a extremo (un enlace → una nota) o desacoplado: cada etapa de la canalización (descarga / transcripción / extracción de fotogramas / comentarios / resumen / exportación / mejora / limpieza) es una herramienta MCP independiente. Si solo quieres usar un paso, o solo quieres conocer el contenido del video, se puede satisfacer. No es necesario iniciar ningún servicio backend.

⚡ Inicio rápido

# 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] Cuatro métodos de instalación, detalles de configuración, actualización y seguridad en docs/04-使用手册.md.

Related MCP server: tldw-mcp

📚 Documentación

La documentación completa sobre instalación / configuración / uso / variables de entorno / actualización / seguridad está archivada en docs/ (el README solo conserva una visión general):

• 📇 Índice de documentación

• 🏗️ Diseño de arquitectura

• 📖 Manual de uso — Instalación (4 métodos) · Configuración (asistente setup + CLI) · Variables de entorno · Actualización · Seguridad

• 📜 Registro de cambios

🎬 Casos reales

Dos casos reales de extremo a extremo: uno usa generación directa por AGENT y genera un PDF LaTeX mathnote, y el otro usa generación totalmente automática por LLM y produce Markdown portátil.

Caso 1 · agent_direct + LaTeX mathnote (video de DeepSeek-V4)

Fuente: [闪客] Interpretación profunda de DeepSeek V1~V4! Comprensible para todos, jóvenes y mayores～

Un video + cuatro tipos de materiales externos (artículo / informe técnico / anuncio oficial de WeChat / colección de código abierto) → generación directa por AGENT de notas refinadas, y salida de PDF LaTeX mathnote (plantilla de KaiTi chino):

Aspectos destacados: flujo completo agent_direct (sin clave LLM, el agente lee la transcripción + imágenes de fotogramas + comentarios y escribe las notas) · integración cruzada de múltiples fuentes (video × artículo × informe técnico × lista de código abierto) · refinamiento conservando el original (copias dobles note.md / note_original.md) · PDF LaTeX mathnote (reparación adaptativa de fuentes faltantes / desbordamiento de líneas / deduplicación de citas). El registro completo del proceso está en examples/agent-direct-deepseek-v4-mathnote/README.md.

Caso 2 · Generación totalmente automática por LLM + Markdown portátil (videos en paralelo)

Prompt minimalista (3 enlaces de Bilibili + directorio de salida, sin explicar ningún parámetro) → totalmente automático ejecuta verificación del entorno → reconocimiento de enlaces → descubrimiento de proveedor/modelo → confirmación de parámetros → videos en paralelo → refinamiento basado en subtítulos tras la generación, produciendo 3 notas portátiles refinadas (note.md + capturas en Assets/ + sección «Opiniones de la audiencia», conservando note_original.md para comparación).

• IELTS: desmontando mitos + desglose de las cuatro secciones (escucha/lectura/escritura/habla) + 179 palabras de alta frecuencia + 15 marcos lógicos

• Medicina forense: un forense con 43 años de experiencia «analiza escena por escena» comparando cine y realidad, refinado y ampliado a 12 secciones

• Transformer: explicación detallada del mecanismo de autoatención, 18 capturas distribuidas según la línea de tiempo de la clase

El registro completo del proceso está en examples/note-generation-example/README.md.

🗺️ Mapa de la canalización

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 🔄 Flujo completo de extremo a extremo

En el modo de extremo a extremo solo necesitas dar un enlace: generate_note ejecuta toda la canalización de forma asíncrona y devuelve task_id; usa el ligero get_task_status para sondear instantáneas hasta SUCCESS/FAILED/CANCELLED (máximo 3 tareas en curso por proceso, no envíes en paralelo en el mismo mensaje). cancel_note es una cancelación cooperativa. La «generación directa por AGENT» usa prepare_note_material — solo prepara el paquete de materiales, sin llamar al LLM configurado, el agente lee la transcripción, mira las imágenes y escribe las notas por sí mismo.

1 📥 Descarga y análisis de plataforma

inspect_video identifica la plataforma (bilibili / youtube / douyin / tiktok / kuaishou / local; fuera de las 6 plataformas integradas devuelve platform:"generic" y usa automáticamente la extracción genérica de yt-dlp que cubre 1800+ sitios) + verifica la validez del enlace (si es inválido, da la razón directamente) + divide los videos multiparte de Bilibili / listas de reproducción de YouTube en urls que se pueden enviar de forma independiente por episodio (sin descargar). Las cookies de la plataforma se gestionan con ! videonote login bilibili / ! videonote setup, no las pases a través de MCP. Los subtítulos de la plataforma (incluidos los subtítulos IA de Bilibili) se usan preferentemente de forma interna por generate_note, sin herramienta independiente.

2 🎙 Transcripción de voz (ASR)

La transcripción de voz (ASR) la completa generate_note internamente: prioriza los subtítulos de la plataforma (incluidos los subtítulos IA de Bilibili); si no hay subtítulos, transcribe. Motores disponibles: fast-whisper (local) / groq / bcut / kuaishou (nube) / mlx-whisper (GPU Apple Silicon en macOS) / funasr (óptimo para chino, VAD + puntuación automática). La gestión de motores y modelos se hace por CLI: ! videonote transcriber set/download; consulta el estado con get_config().

3 🖼️ Comprensión visual del video (extracción de fotogramas)

generate_note admite directamente parámetros de comprensión de video: video_understanding=True + video_interval (por defecto 6s) + grid_size (por defecto [3,3]), envía las imágenes en cuadrícula al LLM multimodal para que «vea» las imágenes.

4 💬 Danmaku y comentarios

Añadir include_comments=True + comments_limit (por defecto 20) a generate_note organiza en las notas el flujo de danmaku y las opiniones frecuentes de la sección de comentarios, añadiendo la sección «Opiniones de la audiencia» (requiere SESSDATA de Bilibili; si la obtención falla no bloquea la tarea).

5 ✍️ Resumen y notas con IA

Admite 9 estilos: minimal / detailed / academic / tutorial / xiaohongshu / life_journal / task_oriented / business / meeting_minutes; format=["screenshot"] produce notas portátiles (note.md + Assets/, con referencias relativas que se pueden trasladar por completo). La configuración de proveedor/modelo/transcriptor se hace siempre por CLI (! videonote providers set / ! videonote transcriber set); consulta de solo lectura con get_config(). agent_direct se genera directamente por el AGENT.

6 📤 Exportación en múltiples formatos

Para formatos mecánicos usa export_transcript (srt / vtt / json) — renderizado determinista (conversión de línea de tiempo), sin consumir LLM, devuelve rutas file://. Los formatos creativos (mapas mentales / tarjetas flash / LaTeX / typst / plantillas personalizadas del usuario) los genera el Agent basándose en el borrador MD + plantillas SKILL (LaTeX incluye plantillas Math Note / English Article: estilo de notas de matemáticas/ciencias, estilo de documentos en inglés/esquemas de presentación; typst incluye la plantilla zju-lab: estilo de notas de ciencias/ingeniería, informes de laboratorio, artículos, con el emblema de ZJU).

7 🎛️ Mejora de audio

merge_audio fusiona múltiples grabaciones / segmentos de reuniones / varios videos locales en un wav mono de 16kHz y luego transcribe. El preprocesamiento de audio (normalización a 16kHz + división automática de archivos muy largos >1800s, con reducción de ruido opcional) está desactivado por defecto, con cero dependencias obligatorias. diarize_media hace separación de hablantes (pyannote es una dependencia pesada opcional, requiere HF_TOKEN + autorización del modelo).

8 🗂️ Gestión y limpieza de tareas

Cada tarea tiene una carpeta note_results/{task_id}/: raw/ (medios descargados) + gen/ (transcripción/notas/fotogramas/exportaciones) + archivos de control; el índice global de tareas está en la tabla SQLite video_tasks (con títulos semánticos). list_tasks enumera todas las tareas (identificadas por título semántico), cleanup_note(dry_run=True) primero consulta y luego limpia, cleanup_note / cleanup_all limpian por tarea / globalmente (por defecto conservan configuración y modelos), health_check verifica que FFmpeg / base de datos / whisper estén listos.

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

🏆 Mejores prácticas

• Estudio y preparación de exámenes: extremo a extremo + comprensión de video + optimización posterior basada en subtítulos, para dominar el curso a fondo.

• Actas de reuniones: merge_audio fusiona grabaciones segmentadas → diarize_media separa hablantes → estilo meeting_minutes.

• Lectura profunda de conferencias: tras la generación de extremo a extremo, el agente refina basándose en los subtítulos completos y completa los detalles por capítulos.

• Apreciación de videos: activa la integración de danmaku + comentarios, las notas incluyen la sección «Opiniones de la audiencia».

• Extremo a extremo: un enlace con generate_note (descarga/transcripción/resumen/comentarios completados internamente); solo preparar materiales con prepare_note_material.

• Casos reales: el registro completo de los casos está en examples.

🤝 Cómo contribuir

• Rama de funcionalidad → PR → dev (el smoke test de CI debe estar en verde); cuando dev esté estable, PR → main (rama protegida, requiere revisión).

• El flujo, la nomenclatura de ramas y la autoverificación antes de confirmar están en CONTRIBUTING.md.

🙏 Agradecimientos

Gracias a la comunidad y a todos los contribuyentes, a Glama por incluir el servidor MCP, y a todas las dependencias de código abierto y la inspiración de los proyectos de canalización upstream.