BiliNote-MCP

中文 · English

视频链接 → AI Markdown 笔记。基于 BiliNote 核心能力封装成的 MCP Server（Model Context Protocol）+ Claude Code Skill：给 agent 一个链接，它下载、转写、总结，交回一份结构化笔记 —— 全程无需启动后端。

📦 仓库：HuangYincan/BiliNote-MCP

✨ 特性

• 🗜️ 内嵌流水线 —— 下载（yt-dlp）→ 字幕/转写（本地 faster-whisper 或云端 groq/bcut）→ 视频理解（按间隔抽帧，多模态 LLM 看画面） → LLM 总结 → Markdown 笔记。全部逻辑在本仓库内，无需启动 BiliNote 的 FastAPI 后端与 Web UI。

• 🧠 无 RAG —— agent 拿到 Markdown 后自己阅读、自己回答，不需要 ChromaDB / embedding，轻量即用。

• 📦 自包含 —— app/ 目录复制自上游（见 VENDOR.md），pip / uv 一键安装。

Related MCP server: tldw-mcp

快速开始（TL;DR）

# 装：一条命令装好 Skill + MCP
claude plugin marketplace add HuangYincan/BiliNote-MCP
claude plugin install bilinote@bilinote

# 配：LLM key + 语音转写引擎（隐藏输入 key）
bilinote-mcp setup

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

bilinote-mcp 是 CLI 简写，未在 PATH 时用 uvx --from git+https://github.com/HuangYincan/BiliNote-MCP bilinote-mcp ...（见 前提条件）。

真实端到端使用示例

只给「3 个 B 站链接 + 输出目录」、一个参数都没说明，agent 就自动跑完 参数确认 → 多视频并行 → 视频理解截图 → 弹幕/评论整合 → 基于字幕精修，产出三份带截图、含「观众观点」的便携精修笔记：

• 雅思教父刘洪波的雅思真经第一课 → notes/ielts-true-class/note.md

• 和解剖了4000具尸体的法医，一起看了影片中的尸体 → notes/forensic-doctor-reacts/note.md

• 李宏毅 | 自注意力机制和Transformer详细解析 → notes/transformer-self-attention/note.md

完整过程记录（前置参数 / Prompt / 参数确认对话 / 输出结果）见 examples/note-generation-example/README.md。

💡 以下从「安装」到「工具参考」都写得尽量详细，主要是给 Agent 看的（Claude Code 等）。人类完全不必逐条照做 —— 直接对 agent 说一句「帮我安装这个 MCP 并生成视频笔记」，它就会照着下面的命令一步步执行。

安装

前提条件

• uv（Python 包管理器，必需 —— uvx / uv tool 方式装 MCP 和 CLI 都靠它）： curl -LsSf https://astral.sh/uv/install.sh | sh 或 brew install uv

  没有 uv？走「方式四」，脚本内置 pip 兜底。

• Python ≥ 3.11，<3.14（推荐 3.12，.python-version 已锁定）

• FFmpeg（音频/视频处理必需）：brew install ffmpeg（Linux：apt install ffmpeg）

• LLM 供应商 API Key（见配置）

• 本地转写：本地 whisper 需先下载模型 bilinote-mcp transcriber download <size>（tiny/base/small/medium/large-v3/large-v3-turbo），或改用云端 groq / bcut（免下载）

• GPU 加速（可选）：

  • NVIDIA / Linux：whisper 默认 CPU；想用 CUDA，装工具时带 --with torch（CUDA 版 torch），推理时自动检测 GPU，否则回退 CPU

  • macOS Apple Silicon：用 mlx-whisper 走 GPU —— 装工具时 --with mlx-whisper，切引擎 bilinote-mcp transcriber set mlx-whisper --size small

• CLI 命令可用形式：正文里的 bilinote-mcp ... 是简写，等价于：

  • 有 uv：uvx --from git+https://github.com/HuangYincan/BiliNote-MCP bilinote-mcp ...（--from 必须带 git+ 前缀）

  • 方式四（pip 装的 venv）：<仓库路径>/.venv/bin/bilinote-mcp ...

  • 想让 bilinote-mcp 直接可用：uv tool install --from git+https://github.com/HuangYincan/BiliNote-MCP bilinote-mcp + uv tool update-shell 加入 PATH

方式一：插件 marketplace —— Skill + MCP（推荐）

claude plugin marketplace add HuangYincan/BiliNote-MCP
claude plugin install bilinote@bilinote

两条命令同时装好 Skill + MCP server（MCP 走 uvx，每次会话自动拉最新 commit）。装完重启会话（或 /reload-plugins）。运行数据统一在 ~/.local/share/bilinote-mcp/。

插件默认的 MCP 不含 mlx-whisper（可选依赖，仅 macOS；默认加会让 Linux/Windows 装不上）。想在 MCP 里用 mlx-whisper，手动覆盖 MCP 命令：

claude mcp add bilinote -- uvx --from git+https://github.com/HuangYincan/BiliNote-MCP --with mlx-whisper bilinote-mcp

手动注册后会话用的是这份（claude mcp list 显示它即生效）。若与插件同名 bilinote 冲突/不生效，先 claude mcp remove bilinote 再重加，或改用 ~/.local/bin/bilinote-mcp（uv tool install --with mlx-whisper 装的那个）作为 MCP 命令。

方式二：只装 MCP（不装 Skill）

claude mcp add --scope user bilinote -- uvx --from git+https://github.com/HuangYincan/BiliNote-MCP bilinote-mcp

即方式一的 MCP 部分。MCP server 是会话级常驻进程（会话开始启动一次，工具调用不重新拉起）。

方式三：uv tool install —— 固定版本、启动最快

uv tool install --from git+https://github.com/HuangYincan/BiliNote-MCP bilinote-mcp
claude mcp add bilinote -- "$HOME/.local/bin/bilinote-mcp"

每次会话直接启动进程（约 1s）、不访问仓库；版本被固定，更新需重跑上面的 uv tool install --force。

macOS Apple Silicon 想用 MLX Whisper（更快的本地转写，可选依赖）：安装时带上 uv tool install --force --from git+https://github.com/HuangYincan/BiliNote-MCP bilinote-mcp --with mlx-whisper

方式四：克隆 + install.sh

git clone https://github.com/HuangYincan/BiliNote-MCP.git
cd BiliNote-MCP && ./install.sh

无 uv 也能用（脚本用 pip 建 .venv）。install.sh：创建 venv → 注册 MCP → 安装 Skill → 自动弹出 bilinote-mcp setup 向导。非交互终端会跳过，可稍后手动跑。

配置（装完必做）

安装只让 MCP / Skill 跑起来；LLM API key 和语音转写引擎需单独配置（key 是你的、模型要选）。所有方式共用同一数据目录（~/.local/share/bilinote-mcp/），配好即会话内生效。

交互向导 setup（推荐，随时可反复进入修改）

bilinote-mcp setup        # 未在 PATH 时：uvx --from git+https://github.com/HuangYincan/BiliNote-MCP bilinote-mcp setup

方向键选择 + 高亮、左键返回上一级、每步自动清屏不留历史；不是一次性程序，随时重跑即可改配置：

• ① LLM 供应商：选一个填/改 key、改 base_url、新增中转站；每供应商可检测连接（验证 key/base_url）、列出可用模型并选默认模型（默认模型持久化，生成笔记未指定模型时自动使用）；

• ② 语音转写引擎：选引擎 + 模型尺寸，本地模型未下载会提示下载；

• ③ 其他：平台 Cookie（平台下拉选择）、默认笔记位置（持久化保存）、视频理解默认（开/关 + 帧间隔秒数，持久化保存）、评论/弹幕整合默认（开/关 + 评论条数，持久化保存，需 B 站 SESSDATA）、笔记默认（default_style 默认 detailed / default_screenshot 默认关 / agent_direct 默认关，持久化保存）—— 全自动模式套用这些默认（会先列出完整参数清单给用户确认）。

手动 CLI（key 不进对话）

# LLM 供应商
bilinote-mcp providers list                                    # 查看（key 掩码）
bilinote-mcp providers set deepseek --api-key 'sk-你的key'      # 给内置供应商填 key
bilinote-mcp providers add --name 中转站 --api-key 'sk-...' --base-url 'https://relay...'   # 新增中转站
bilinote-mcp providers test deepseek                            # 检测连接 + 列出可用模型
bilinote-mcp providers test deepseek --default deepseek-chat    # 检测并设为默认模型

# 语音转写引擎
bilinote-mcp transcriber list                                  # 查看当前引擎与就绪状态
bilinote-mcp transcriber set fast-whisper --size small          # 切本地 whisper
bilinote-mcp transcriber set groq                               # 切云端
bilinote-mcp transcriber download small                          # 下载 fast-whisper 模型
bilinote-mcp transcriber download small --engine mlx-whisper     # 下载 mlx-whisper（macOS）

# B 站（用 AI 字幕跳过语音识别）
bilinote-mcp login bilibili     # 扫码登录，自动获取并保存 SESSDATA（AI 字幕需登录态）

转写引擎：fast-whisper（本地）/ groq / bcut / kuaishou（云端）/ mlx-whisper（仅 macOS Apple Silicon，GPU 加速）。

本地 whisper 尺寸：tiny / base / small / medium / large-v3 / large-v3-turbo（turbo 更快、精度略低于 large-v3）。

设备：whisper 会自动检测 CUDA（装了 torch+CUDA 就用 GPU，否则回退 CPU）；macOS 的 GPU 用 mlx-whisper。CLI transcriber download 用 CPU 只是因为它只下载权重、不推理（device 参数不影响下载结果）。

没有 LLM API key？

• 本地免费：装 Ollama 并 ollama pull llama3。内置 ollama 供应商已预置（http://127.0.0.1:11434/v1，无需 key），list_models("ollama") 有模型即可用。

• 免费额度：Groq / DeepSeek 等有免费 tier，注册后 providers set 填 key。

• 对 agent 说「我没有 LLM key」，它会先查 Ollama 是否可用，再引导你注册。

使用

给 agent 用（Claude Code 等）

对 agent 说「给这个视频做笔记」+ 链接即可，标准流程：

1. health_check —— 确认 FFmpeg / 数据库就绪；

2. list_providers —— 确认供应商 key=已填（看不到明文）；没有就先用 CLI 配；

3. generate_note(video_url=..., provider_id=..., model_name=...) —— 拿 task_id；

4. get_task_status(task_id) 轻量快照轮询，等到 SUCCESS/FAILED/CANCELLED（任务一次只发一个，server 有进行中任务时会拒绝新提交；不要并行塞多个 generate_note）；

5. 拿到 result.markdown 后，agent 自己阅读 Markdown 回答你的问题 —— 不需要额外 RAG；

6. 问你是否要根据笔记 + 提取的字幕（result.transcript）做后续优化（补齐细节/修正不一致/增强结构）—— agent 侧精修，不新增工具。

全自动 / 手动模式 + AGENT 直接生成

任务开始时 agent 会先问「全自动」还是「手动」：

• 全自动：用 setup ③ 的默认解析出完整参数清单（生成方式/LLM 模型（或选 AGENT 直接生成）/ default_style（默认 detailed）/ 视频理解默认 / 评论默认 / 截图默认 / 生成后是否后续优化），一次性列给用户确认、不逐个问；用户要改某项再以提问方式改，确认后 generate_note 不传 style / screenshot / video_understanding / include_comments / agent_direct 即套默认。「AGENT 直接生成」在选 LLM 模型阶段提供（默认用配置 LLM）。

• 手动：逐个确认参数（LLM 模型、笔记风格、视频理解、评论/弹幕、截图、是否 AGENT 直接生成），确认完再生成。

AGENT 直接生成（agent_direct）：在选 LLM 模型阶段提供选项 —— 手动模式问「用哪个模型，还是 AGENT 直接生成」；全自动模式默认用配置 LLM，可在参数清单里改选。开启后不走配置的 LLM，由 agent 自己写笔记：

1. prepare_note_material(video_url, video_understanding?, video_interval?, include_comments?, comments_limit?) → task_id；

2. get_task_status(task_id) 轮询到 SUCCESS → 拿到素材包（result.transcript.full_text 完整转写、result.frames 抽帧图、result.comments_danmaku 评论/弹幕）；

3. agent 读转写 / 用 Read 看图 → 自己生成 Markdown（问风格，默认 detailed；有评论/弹幕时笔记含「观众观点」章节）→ 呈现。

转写过长（如 2h 视频）时按章节分段精修或让用户指定重点。其余流程（health_check / validate_url / 轮询 / 后续优化）与常规一致。

手动工具速查（非敏感配置）

涉及 key 的操作一律走 CLI（对话外），工具只做非敏感配置 —— 见安全说明。

进阶：视频理解（画面切片）

想让 agent 按时间间隔抽视频画面发给多模态 LLM（如 qwen-vl / gpt-4o）做「看画面」的理解，generate_note 直接支持：

generate_note(video_url=..., provider_id="qwen", model_name="qwen-vl-plus",
              video_understanding=True, video_interval=6, grid_size=[3, 3])

• 每 video_interval 秒抽一帧，按 grid_size 拼成网格图，以 base64 内嵌发给 LLM；

• 需多模态（vision）模型，deepseek-chat 等纯文本模型不支持；

• grid_size 缺省自动 [3, 3]（format=["screenshot"] 截图模式为 [2, 2]）；

• 默认值可在 setup ③ 配置（默认关 / 6s）：agent 未显式传 video_understanding / video_interval 时自动套用（手动模式下 SKILL 仍要求先问用户本次是否启用 + 间隔，只有用户说「你定/用默认」才用默认值；全自动模式套默认（先列出参数清单待确认））；

• 想在 markdown 里按 *Screenshot-mm:ss 标记插单张截图，用 format=["screenshot"]（区别于整片帧网格）。

进阶：整合弹幕+评论区观点

想让笔记把 B 站弹幕和评论区的高频观点也整理进去（哪些弹幕刷屏、评论区在聊什么），generate_note 加：

generate_note(video_url=..., ..., include_comments=True, comments_limit=20)

• 整合弹幕+评论区观点，让笔记不仅来自音轨，还能反映观众讨论；

• 笔记会新增一节「观众观点」：总结弹幕刷屏/评论区反复出现的观点、补充、纠错（引用实际内容，不捏造）；无可总结时写「（无）」；

• comments_limit 控制抓取的评论条数（默认 20）；

• 需 B 站 SESSDATA（登录态）：没配则评论拿不到 —— 先 bilinote-mcp login bilibili 扫码（或 set_downloader_cookie(platform="bilibili", cookie="SESSDATA=...")）；

• 抓取失败不阻断任务：拿不到评论/弹幕时笔记照常生成，跳过该部分即可；

• 只想单独拉数据看，用 fetch_comments(video_url, limit=20) / fetch_danmaku(video_url) 两个工具；

• 默认值可在 setup ③ 配置（默认关 / 20条）：agent 未显式传 include_comments / comments_limit 时自动套用（手动模式下 SKILL 仍要求先问用户本次是否整合，只有用户说「你定/用默认」才用默认值；全自动模式套默认（先列出参数清单待确认））。

进阶：图片插入（便携笔记）

想让笔记带截图、且能整体搬迁，generate_note 加：

generate_note(video_url=..., provider_id=..., model_name=..., screenshot=True, format=["screenshot"])

• 产出便携笔记：note_dir/note.md + note_dir/Assets/*.jpg，markdown 里用相对引用 ![...](Assets/xxx.jpg)；

• 任务结果里 result.note_dir 指向该目录（agent 会告诉你笔记和图片在哪）；

• 保存位置优先级：generate_note(..., notes_dir="/你/指定/的目录") → BILINOTE_NOTES_DIR 环境变量 → 默认 note_results/{task_id}/；

• 指定了 notes_dir 时，每篇笔记一个文件夹：<notes_dir>/<笔记标题>/note.md（标题取 LLM 生成的笔记 H1，回退视频标题；冲突自动加短 task_id 后缀）—— 即使不插图片也会写文件（适合「生成笔记到某文件夹」，且多篇互不覆盖）；

• 前提：screenshot=True 让 LLM 在笔记里生成 *Screenshot-[mm:ss] 标记，format=["screenshot"] 负责替换成图片；配视频理解（video_understanding=True）时画面理解与截图更自然。

进阶：清理与存储（cleanup）

任务产生的文件（下载的视频/音频、转写、截图、临时文件）会堆积占存储。AGENT 可自助清理：

• 先查后清：get_task_files(task_id) —— 列出该任务在磁盘上相关的文件/目录（manifest 记录 + {task_id}* 前缀扫描），返回 {task_id, manifest_paths, existing}。

• 按任务清理：cleanup_note(task_id, include_note=False) —— 删该任务中间产物（视频/音频/转写/截图/dl_{task_id}/），默认保留最终笔记 note.md；include_note=True 连笔记一起删。

• 全局清理（恢复出厂）：cleanup_all(include_config=False, include_models=False) —— 清空 note_results/*、static/screenshots/*、logs/*；默认保留 config/（LLM key / cookie / 转写设置）与 models/（模型可复用、重下成本高），include_config=True / include_models=True 才一起清。数据库记录（bili_note.db）不动。

安全：只删 manifest 记录 / 明确前缀模式的文件，删除前 resolve() 校验在数据目录内（防路径穿越），失败逐条跳过并返回统计。

工具参考

环境变量（可选）

会话内串行 + 多会话并行：每个 Claude Code 会话独立起一个 MCP server 进程。本会话内任务强制串行 —— generate_note 在已有进行中任务时会直接拒绝（必须一次一个：提交 → 等到 SUCCESS/FAILED/CANCELLED → 再提交下一个）；多个会话可各自并行生成不同视频的笔记（互不干扰）。注意：Claude Code 客户端对「同一条消息里多个并行 MCP 工具调用」处理不稳（最后一个响应会卡死、任务也未提交）—— 所以即使跨任务，也不要在同一消息里并行塞多个 generate_note。多任务轮询请用轻量 get_task_status(task_id) 快照轮询；wait_for_note 是阻塞调用，会卡住当前轮次。需要取消进行中任务用 cancel_note(task_id)。注意：whisper / MLX 转写吃 CPU/内存，太多会话并行会拉满机器；所有会话共用同一个 SQLite，极端并发下可能偶发写冲突。

更新

各安装方式的更新命令：

Skill/插件三步各有用：① marketplace update 拉最新 commit；② disable 让 install 不跳过；③ install 重装到最新。缺任一步都可能用旧版（install 单独会被「已安装」跳过）。

安全（API Key）

红线：不要在对话里把 key 发给 agent。 agent 的对话内容会发送到它的 LLM 上游，key 一旦出现在对话里就等于交给了上游。key 一律在独立终端走 CLI（! 前缀的命令文本也在对话里，同样不行）：

bilinote-mcp providers set deepseek --api-key 'sk-你的key'      # 独立终端执行
bilinote-mcp providers list                                     # 查看（key 掩码）

• agent 只需要知道「key 填没填」：list_providers 返回掩码（sk-S***cdef），add/update 工具不回显 key，相关日志已打码。

• 存哪：key 只存在本地 SQLite（~/.local/share/bilinote-mcp/bili_note.db 或源码 data/），已 gitignore，不会进 GitHub。

• 提醒：key 以明文存在本地数据库（与上游 BiliNote 一致）。若机器可能被他人使用，建议后续用系统 keychain 加密存储。

Skill

仓库自带 Claude Code Skill —— skills/bilinote/SKILL.md，它教 agent 用上面的流程一句话完成「视频 → 笔记」（触发词：「生成视频笔记」「帮这个视频做笔记」「从 XX 链接做笔记」）。核心 SKILL 精简为「强制规则 + 工作流」，工具接口 / 配置 / 故障排查在 skills/bilinote/reference/ 下（agent 需要时按需 Read）。

通过插件 marketplace 安装（同时装好 Skill 与 MCP server）：

claude plugin marketplace add HuangYincan/BiliNote-MCP
claude plugin install bilinote@bilinote

装好后重启会话（或 /reload-plugins），对 Claude 说「帮我给这个视频做笔记」+ 链接，Skill 自动触发并驱动 MCP 工具。

文档

详细中文文档见 docs/：

• 目的与背景

• 架构设计

• 预期效果

• 使用手册

• 更新日志

开发流程

• 日常开发在 dev 分支：功能分支 → PR → dev（CI 必须绿）；

• 发布：dev 稳定后 → PR dev → main（CI + review 通过才合）→ 打 vX.Y.Z tag → Release workflow 自动发 GitHub Release；

• main 有分支保护：直接 push 被拒，只接受 PR 合入 —— 保证 main 永远可用（uvx --from git+ 安装直接拉 main）；

• 稳定安装用 tag：uvx --from git+https://github.com/HuangYincan/BiliNote-MCP@v0.1.0 bilinote-mcp（追新去掉 @v0.1.0）。

开发版（dev 分支尝鲜）

dev 分支有未发布的新功能（尝鲜/测试用）。想提前用 dev（从 main 切到 dev）：

MCP 工具指 dev（覆盖插件的 main MCP）：

claude mcp remove bilinote                                 # 如果先前在 main：先移除插件默认的 main MCP，再覆盖成 dev（同名 add 才能生效）
claude mcp add --scope user bilinote -- uvx --from git+https://github.com/HuangYincan/BiliNote-MCP@dev bilinote-mcp

SKILL 也指 dev（marketplace 指到 dev 分支）：

claude plugin marketplace add HuangYincan/BiliNote-MCP@dev
claude plugin disable bilinote@bilinote
claude plugin install bilinote@bilinote

重启会话（或 /reload-plugins）生效。

已经 pin 到 dev 后，代码更新了：只需 claude plugin marketplace update bilinote（拉到 dev 最新 commit，ref: dev 会保留），再 disable + install；不用重新 add @dev。只有 marketplace 被切回 main 时才需要再 add ...@dev。

切回 main（稳定版）：

claude mcp remove bilinote                                   # MCP 恢复插件默认（main）
claude plugin marketplace add HuangYincan/BiliNote-MCP       # marketplace 回 main
claude plugin disable bilinote@bilinote
claude plugin install bilinote@bilinote
# /reload-plugins

CLI 用 dev（PATH 上的 bilinote-mcp 若是 main 固定版）：uvx --from git+https://github.com/HuangYincan/BiliNote-MCP@dev bilinote-mcp setup

注意：

• dev 与 main 共用数据目录 ~/.local/share/bilinote-mcp/：LLM key / SESSDATA / 转写配置自动带过来，不用重配；但共用同一 SQLite，别两个同时跑任务。

• marketplace 指 dev 会替换生产 marketplace（不并存），测完记得切回 main。

• git+...@dev 是 uv/uvx 的分支 ref 语法；不带 ref 的默认安装拉的是 main（稳定）。

• marketplace 指 dev 只换 SKILL；MCP 工具要手动 @dev 覆盖（marketplace.json 里的 uvx 无 ref，仍拉 main）。

• dev 分支功能未发布，仅尝鲜/测试。

相关

• 上游项目：https://github.com/JefferyHcool/BiliNote